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INTRODUCTION 


-This  workshop  is  the  result  of  over  a  year's  work  by  a  group  of  people  who  feel  that 
software  documentation  has  an  important  place  in  software  and  overall  systems 
development.    The  purpose  of  the  workshop  was  to  review  current  documentation  standards 
and  guidelines,  to  provide  a  forum  for    information  exchange,  and  to  propose  and  discuss 
future  guidelines  and  standards  for  software  documentation. 

In  order  to  determine  the  scope  of  the  workshop,  to  obtain  some  idea  of  what  topics 
would  be  of  interest,  and  who  the  audience  might  be,  a  "Call  for  Indications  of 
Interest",  was  issued,  with  a  deadline  of  May  15,  1980.    The  response  was  generous,  and 
by  October  1980,  a  preliminary  program  was  finalized. 

The  program  was  planned  to  be  a  regional  affair,  covering  commuting  distance  from 
Washington,  D.C.,  Maryland,  and  Virginia. 

In  the  following  pages  there  are  presented  introductions  by  session  moderators,  papers 
presented,  comments  by  discussants,  recorders,  and  members  of  the  audience. 

It  is  hoped  that  the  record  of  this  workshop  will  contribute  to  the  identification  and 
clarification  of  software  documentation  issues,  will  help  in  solving  some  of  the  issues, 
and  will  thus  contribute  to  the  development  of  better  and  more  useful  information 
systems. 

The  final  program,  as  it  was  presented,  has  been  reproduced,  and  references  to  page 
numbers  in  the  Proceedings  provide  an  index  to  the  presented  material. 
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PROGRAM 

8:30  a,m.  REGISTRATION 

9:15  a.m.    GENERAL  SESSION  -  OPENING  REMARKS 

Welcome:    James  H„  Burrows,  Director,  Institute  for  Computer  Sciences 
and  Technology,  National  Bureau  of  Standards 

Charge  to  Workshop:    Albrecht  J.  Neumann,  Institute  for  Computer 
Sciences  and  Technology,  National  Bureau  of  Standards 

10:00  a„m„  BREAK 

10:15  a.m.  -  12:30  p.m.    MORNING  PARALLEL  SESSIONS 

SESSION  A:    Applying  Documentation  Standards  -  Case  Studies 

Moderator:    Charles  H„  Dickson,  U„S,  Department  of  Agriculture 

The  papers  highlight  various  problems  encountered  by  software  groups 
both  inside  and  outside  the  Federal  government  as  they  have  attempted 
to  cope  with  the  array  of  presently  existing  software  documentation 
standards. 

User  Experience  and  Compatibility  in  Documentation  Standards  -  A 
Summary 

Betty  F.  Maskewitz,  Oak  Ridge  National  Laboratories 

Systems  Development  Methodology  and  Documentation  Practices 
Louis  J.  O'Korn,  Chemical  Abstract  Service 

Experience  in  Application  of  Software  Documentation  Standards 
William  Bryan  and  Stan  Siege! ,  CTEC,  Inc. 

Case  Studies,  Management  Guidance  and  Quality  Criteria  for 

Software  Documentation 

James  N.  Orton,  Westinghouse  Company 

Experiences  in  Software  Standards  Selection  and  Application  -  A 
Case  History 

Thomas  L„  Hannan  and  Alice  Wong,  Federal  Aviation  Administration 

Discussants:    Bruce  E.  Baxter,  Internal  Revenue  Service 
Stephen  B.  Leibowitz,  Library  of  Congress 

Recorder:    R.  J.  Gavin,  Federal  Deposit  Insurance  Corporation 

SESSION  B:    Documenting  for  Operation  and  Maintenance 

Moderator:    Charles  L.  Gerhardt,  U„S.  Department  of  Agriculture 

FIPS  documentation  guidelines  exist  for  the  Initiation  and 
Development  phases  but  not  for  the  Operation  phase  of  the  software 
life  cycle.    It  is  during  the  latter  phase  that  software  is 
maintained,  evaluated,  and  changed  as  additional  requirements  are 
identifiedo    Is  there  a  need  for  documentation  guidance  for  this 
phase?    This  session  explores  the  question  by  presenting  case 
studies  of  governmental  and  non-governmental  software,  including 
commercial  products.    Software  certification,  change  control,  config- 
uration management,  and  end  user  documentation  needs  are  discussed. 
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The  Development  and  Implementation  of  Uniform  ADP  Documentation 
Standards  at  FAA 

Harvey  P.  Kaplan,  Federal  Aviation  Administration,  U.So  Department 
of  Transportation 

Supplemental  Documentation  of  Modifications  to  Software  Products  on 
Small  to  Medium  Sized  Systems 
Henry  A.  Lewis,  DCD  Company 

Operations  Documentation  Standards  -  Online,  Realtime  Versus  Offline, 
Batch 

Deborah  A.  Harman,  Online  Computer  Library  Center 

Documentation  for  Operation  Phase  of  Systems  Life  Cycle 

Robert  A.  Larson,  Forest  Service,  U.S.  Department  of  Agriculture 

A  Proposed  Guideline  for  Documentation  of  Computer  Programs  and 
Automated  Data  Systems  for  the  Operation  Phase 
Thomas  M.  Kurihara,  U.S.  Department  of  Transportation 

Discussants:    James  Mo  Stierwalt,  Booz-Allen  &  Hamilton,  Inc. 

Mary  Ann  Engelbert,  Naval  Data  Automation  Command 

Recorder:    Nancy  Mae  Bonney,  Dynamac  Corporation 


^  SESSION  C:    Tools  for  Improved  Documentation 

^Moderator:    Raymond  C.  Houghton,  National  Bureau  of  Standards 

Documentation  Tools  not  only  provide  a  means  for  developing  more 
accurate  and  less  costly  documentation,  but  they  can  also  enforce 
the  development  of  standard  documentation  and  provide  a  consistent 
means  for  obtaining  information  about  a  software  system. 

State  of  the  Art  Documentation:    What  is  it?    How  Does  it  Affect 
Documentation  Standards? 

So  Lee  Henry,  American  Management  Systems,  Inc. 
The  EAS-E  Approach  to  Documentation 

A.  Malhotra,  Ho  M.  Markowitz,  D.  P.  Pazel ,  Thomas  J.  Watson  Research 
Center,  IBM 

ADD:    An  Automated  Tool  for  Software  Design  and  Documentation 
T.  Co  Ting,  Worcester  Polytechnic  Institute 

An  Approach  to  Computer  Maintained  Software  Documentation 
Bruce  I.  Blum,  The  Johns  Hopkins  University 

Automated  and  Automatic  Documentation 

Linda  K.  Lawrie,  U,S.  Army  Construction  Engineering  Research  Lab. 

Discussants:    Herbert  Hecht,  SoHaR,  Inc. 

Nathan  Relies,  Sperry  Univac 

Recorder:    Sheila  Frankel ,  National  Bureau  of  Standards 

SESSION  D:    Do  Existing  Standards  Work? 

Moderator:    Alfred  R.  Sorkowitz,  U.S.  Department  of  Housing  and 


Urban  Development 


Page 


This  session  deals  with  the  existing  FIPS  38  and  related  documentation 
standards.    The  focus  is  on  how  these  standards  can  be  modified  to  be 
responsive  to  new  initiatives,  such  as  the  emphasis  on  security.  Also 
discussed  will  be  new  methods  for  producing  documents,  such  as  the  use 
of  technical  writing  groups. 

Documenting  Systems  Security 

Ronald  G,  Thies,  U„So  Department  of  Housing  and  Urban  Development  131 


Using  FIPS  PUB  38:    A  Practical  Experience 

Patrick  0' Conor,  Science  Management  Corporation  and  Samuel  T, 

Redwine,  Jr.,  The  MITRE  Corporation  143 

An  Overview  of  the  DOD  Automated  Data  Systems  Documentation  Standard  - 
An  Adaptable  Standard 

Robert  R,  Hegland,  U.S.  Department  of  the  Navy  152 
Discussant:    James  Pottmyer,  U„Se  Department  of  Defense 

Recorder:    Elizabeth  Weinberger,  U.So  Department  of  Health  and  Human  Services  157 


1:00  p.m.    LUNCH,  SPECIAL  SECTION,  NBS  CAFETERIA 
2:00  p.m.  -  4:00  p.m.    AFTERNOON  PARALLEL  SESSIONS 
^    SESSION  E:    Proposals  for  Documentation  Standards 
Moderator:    Trudy  Grieb,  Hadron,  Inc. 


The  papers  propose  approaches  to  documentation  standards  for  the  purpose 
of  overcoming  problems  encountered  in  using  current  -  often  inconsistent, 
sometimes  conflicting  and  awkward  -  documentation  standards. 

Proposed  Approach  to  Standards  for  Documentation  of  Projects  and 
Systems  Based  on  Actual  Requirements 

Trudy  Grieb,  Hadron,  Inc.  160 

A  Proposed  Documentation  Standard  Based  on  a  System  Decomposition  and 
Information  Base  Approach 

Saul  A.  Zaveler,  UoS„  Air  Force  166 


Microcomputer  System  Users  Need  Better  Documentation 

Richard  Ac  Bassler,  The  American  University  174 

Discussants:    Edward  W.  Hurley,  Hadron,  Inc. 

Samuel  To  Redwine,  Jr.,  The  MITRE  Corporation 

Recorder:    Andrea  Papillion,  Hadron,  Inc.  165,  172,  180 

SESSION  F:    Enhancing  Software  Sharing 

Moderator:    Lenore  S.  Maruyama,  Library  of  Congress  ^81 


This  session  considers  different  aspects  of  software  sharing,  which  in  a 
broad  context  encompasses  the  use  of  software  created  by  persons  or 
organizations     outside  one's  immediate  institutional  affiliation. 
Because  of  the  increasing  importance  of  software  sharing  in  all  sectors, 
standards  and  standardized  techniques  have  been  or  are  being  developed 
to  facilitate  the  sharing  process. 
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Effective  Bibliographic  Standards  for  Computer  Software: 

Improved  Documentation  and  the  Need  for  "  Title  Page"  Equivalents 

Sue  A„  Dodd,  University  of  North  Carolina  183 

Standards  for  Bibliographic  Control  of  Machine-Readable  Data  Files 

Lenore  S.  Maruyama,  Library  of  Congress  189 

The  Computer  Program  Abstract  as  Software  Documentation 

Margaret  K„  Butler,  Argonne  National  Laboratory  197 
An  Integrated  Machine-readable  Data  Documentation  System 

Richard  C.  Roistacher,  Bureau  of  Social  Science  Research  203 
Compilation  of  Bibliographic  Data  Element  Dictionaries 

Madeline  M.  Henderson ,  Consul tant  209 

Capital  games:    the  problem  of  compatibility  of  bibliographic  citations 
in  data  bases  and  in  printed  publications 

Hans  Ho  Wellisch,  College  of  Library  and  Information  Services, 

University  of  Maryland  215 

Discussants:    Joel  Lipkin,  King  Research,  Inc„ 

Alan  Wenberg,  National  Technical  Information  Service 

Recorder:    Linda  Tepp,  Library  of  Congress  219 

SESSION  G:    Improving  Human  Interfaces 

Moderator:    Joseph  Psotka,  National  Institute  of  Education  224 

Users  of  software  documentation  face  many  practical  problems  that  can  be 
overcome  by  a  proper  design  of  the  human  interface.    This  session  will 
deal  with  several  interface  characteristics  designed  to  make  documentation 
friendlier,  more  useful,  and  of  higher  quality. 

Designing  Software  Documentation  for  Non-Technical  Users 

V.  Douglas  Hines,  U,S,  House  of  Representatives  225 

Paper  and  Glass:    Graphic  Design  Issues  for  Software  Documentation 

Aaron  Marcus,  University  of  California  230 

The  Comic  Book  Style  of  Documentation  -  Does  it  Transcent  FIPS  38?  — 
Charles  H.  Dickson,  Jr.,  U.S,  Department  of  Agriculture 

Quality  Issues  in  On-Line  Documentation 

Joseph  Psotka,  National  Institute  of  Education  236 

Discussant:    Michael  Feldman,  George  Washington  University  242 

Recorder:    Patricia  Butler,  National  Institute  of  Education 

J  SESSION  H:    Quality  Assurance  for  Documentation 

Moderator:    Virginia  C.  Walker,  U,So  Department  of  Energy  246 

No  matter  how  good  standards  are,  they  are  not  useful  unless  they 
contain  measurable  criteria  which  can  contribute  to  a  quality  product. 
The  papers  in  this  session  touch  upon  several  approaches  to  quality 
assurance  of  documentation. 
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Auditing  Systems  Documentation 

Richard  J.  Thompson,  Chemical  Abstract  Service 


247 


Use  of  the  User's  Manual  as  a  Quality  Control  Tool 
Caroline  S„  Levenson,  Edition,  Inc. 


256 


Requirements  Documentation  -  A  Management-oriented  Approach 
Herbert  Hecht,  SoHaR,  Inc. 


265 


Discussant:    John  R.  Gabriel,  Argonne  National  Laboratory 


274 


Recorder:    Elisabeth  F„  Mullen,  JEM  Associates 


279 


4:00  Pom.  BREAK 


4:15  p.m.  -  5:30  Pom„    CONCLUDING  SESSION 


281 


Each  session  moderator  will  present  a  summary  of  the  session's 
findings  and  recommendations o    This  provides  an  opportunity  for  all 
participants  to  hear  about  the  results  of  all  sessions„    The  session 
moderators  and  discussants  will  also  serve  as  a  panel  to  answer 
questions  from  the  audience. 

5:30  p.m.  ADJOURNMENT 
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Welcoming  Remarks 

James  H.  Burrows 

Director  Institute  for  Computer  Sciences  and  Technology 
National  Bureau  of  Standards 
Washington,  D.C.  20234 

James  H.  Burrows,  Director  of  the  Institute  for  Computer 
Sciences  and  Technology,  welcomed  participants  to  the  Software 
Documentation  Workshop.    His  remarks  emphasized  the  need  for 
software  documentation  by  many  users  throughout  an  organization 
and  throughout  the  software  development  and  maintenance  process. 

Keywords:    documentation  needs;  FIPS;  software  management. 

On  behalf  of  the  Institute  for  Computer  Sciences  and  Technology  (ICST), 
I  am  pleased  to  welcome  all  participants  to  the  Software  Documentation 
Workshop.    ICST  has  responsibility  under  the  Brooks  Act  to  develop  standards 
and  guidelines  for  the  more  effective  management  and  use  of  automatic  data 
processing  (ADP)  by  the  Federal  Government.    One  particularly  critical  area 
of  focus  is  that  of  software  development  and  maintenance.    To  assist  agencies 
in  this  area,  ICST  has  issued  Federal  Information  Processing  Standard  (FIPS) 
publications,  reports,  and  guides  for  software  documentation.    Several  of 
these  documents  are  quite  recent,  and  some  have  been  available  for  some 
time.    We  are  continuing  to  identify  the  user's  needs  for  additional  guidance 
and  help  in  the  software  documentation  process,  and  we  plan  to  issue  additional 
products  in  the  future. 

The  fact  that  this  workshop  is  so  well  attended  suggests  that  many  of  you 
agree  that  software  documentation  is  needed  for  more  effective  use  of  soft- 
ware resources  and  that  software  documentation  processes  must  be  improved. 
I  believe  that  software  documentation  is  vital  to  the  software  development 
and  maintenance  process,  that  it  is  needed  throughout  the  software  planning 
and  development  cycle,  and  that  it  is  needed  by  many  people  throughout  an 
organization. 

No  longer  is  the  development  of  software  a  one  person  process.    Today  most 
programs  are  large  ones,  especially  administrative  applications,  and  files 
are  often  shared  by  many  people. 

Software  documentation  helps  to  bring  discipline  to  an  ADP  activity. 
It  is  useful  in  planning  and  managing  resources,  in  implementing  audits  and 
evaluations,  and  in  planning  and  implementing  computer  security  procedures. 
Software  documentation  also  provides  continuity  to  an  ADP  activity  as  personnel 
and  needs  change.    We  have  all  had  experience  with  a  program  that  disappears 
or  stops  working  when  the  programmer  who  developed  it  leaves.    This  is  costly 
and  inefficient.    Another  reason  why  software  documentation  is  needed  is  to 
promote  common  understanding  and  expectations  about  the  software  both  within 
the  organization,  and,  if  the  software  is  purchased,  between  the  buyer  and 
the  seller.    Documentation  helps  to  define  what  is  expected  and  to  verify 
what  is  delivered.    Further,  software  documentation  provides  flexibility 
within  an  organization  by  enabling  people  to  move  from  one  job  to  another, 
and  to  make  efficient  use  of  their  training. 
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The  individual  entrepreneural  developers  of  software  certainly  need  documen- 
tation because  property  rights  in  copyright  and  patent  right  cases  are  difficult 
to  prove  without  it.    And  in  the  context  of  the  strength  of  the  U.S.  software 
industry,  I  believe  that  good  documentation  is  essential  to  the  ability  of 
U.S.  companies  to  compete  in  international  markets. 

Software  documentation  is  needed  throughout  the  software  life-cycle,  starting 
with  the  software  planning  process,  and  continuing  through  many  stages  to  serve 
different  users  and  changing  needs.    Software  documentation  is  the  management 
trail  that  lets  the  software  developer  and  the  manager  know  where  they  are 
in  the  development  of  a  system. 

As  for  who  needs  software  documentation,  I  believe  that  the  entire  organi- 
zation does  --  planners,  developers,  managers,  testers,  trainers,  maintainers, 
operators,  and  users.    The  number  of  people  involved  varies  with  the  size  of 
the  systems.    Single  user  microcomputers  may  have  only  one  person  who  needs 
documentation,  and  that  is  often  part  of  the  system  itself.    Hov/ever,  for 
very  large  systems  such  as  military  and  airline  reservations,  formal  documen- 
tation is  essential,  and  the  potential  users  are  numerous. 

It  is  clear  that  documentation  is  a  necessary,  but  not  sufficient,  factor 
in  a  well-run  and  disciplined  activity.    No  engineering  discipline  exists 
without  documentation;  it  provides  a  time-ordered  check  list  to  prompt  attention 
to  the  right  things  at  the  right  times.    Documentation  is  not  a  single  process 
for  a  single  user,  but  a  broad-based  process  that  serves  different  needs  and 
different  users.    ICST  is  especially  interested  in  helping  Federal  agencies 
identify  their  needs  for  documentation  and  find  ways  to  achieve  it. 

I  wish  you  a  successful  workshop  and  hope  that  you  make  progress  in 
addressing  this  most  important  issue.    We  look  forward  to  helping  the  Federal 
Government  use  the  ideas  and  the  information  that  develop  in  this  workshop. 
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Charge  to  Workshop 


by 

Albrecht  J.  Neumann 

Institute  for  Computer  Sciences  and  Technology 
National  Bureau  of  Standards 

We  are  meeting  today  under  the  auspices  of  the  Institute  for  Computer  Sciences  and 
Technology  to  discuss  software  documentation  guidelines.    To  put  our  efforts  in  context, 
I  would  like  to  say  a  few  words  about  the  Institute,  the  Workshop  structure,  about 
software  documentation,  and  guidelines. 

The  Institute 

This  workshop  is  sponsored  by  the  NBS  Institute  for  Computer  Sciences  and  Technology. 
This  organization  was  created  as  a  consequence  of  Public  Law  89-306,  dated  October  30, 
1965,  which  is  also  known  as  the  "Brooks  Act".    Under  this  law  NBS  is  responsible  for: 

--  providing  scientific  and  technological  consulting  and  advisory 
services  to  Federal  agencies, 

—  developing  uniform  Federal  automatic  data  processing  standards;  and, 

--  undertaking  necessary  research  in  the  sciences  and  technologies  of  automatic 
data  processing  computer  and  related  systems. 

During  the  past  15  years  almost  100  Federal  Information  Processing  Standards 
publications  (FIPS  PUBs),  including  standards  and  guidelines,  have  been  published  by 
ICST.    Some  of  the  guidelines  we  will  discuss  today  have  been  published  in  this  series. 
As  a  matter  of  policy  these  guidelines  are  being  reviewed  at  certain  intervals.  One 
guideline  which  is  scheduled  for  review  in  the  near  future  is  FIPS  38  (Guidelines  for 
Documentation  of  Computer  Programs  and  Automated  Data  Systems). 

Several  papers  will  deal  with  FIPS  38.    Any  proposals  for  new  guidelines  will  be 
candidates  for  publication  as  a  FIPs. 

Workshop  Design 

Now  I  would  like  to  say  a  very  few  words  about  the  structure  and  design  of  today's 
meeting.    In  planning  for  today's  activities  we  had  several  options.    We  could  have 
planned  to  have  a  series  of  lectures,  or  a  series  of  document  reviews  by  small  groups. 
We  instead  planned  for  parallel  sessions  to  provide  maximum  exposure  of  ideas,  to  a 
large  number  of  people,  hopefully  eliciting  a  large  number  of  comments.    Since  most  of 
the  papers  will  appear  in  the  proceedings  you  will  have  an  opportunity  to  read  the 
material  at  your  leisure  and  at  your  own  pace.    We  have  asked  the  authors  to  discuss  the 
highlights  of  their  papers,  and  have  asked  the  moderators  to  plan  for  maximum  audience 
interaction. 

We  today  are  discussing  Software  Documentation  Guidelines. 

A  few  comments  are  in  order  to  define  a  little  more  precisely  just  what  is  meant 
by  this  term.    Software  covers  a  broad  concept:    it  includes  not  only  computer 
programs,  but  also  descriptions  and  specifications  of  programs,  i.e.,  documentation 
or  programs,  as  well  as  documentation  of  system  functions  and  instructions  for 
people  which  are  needed  to  run  computer  programs.    Also  included  are  data  used 
for  program  and  system  operation. 
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Similarly  Documentation  covers  a  rather  broad  area:    While  computer  programs 
provide  instructions  to  machines  on  how  to  solve  specific  problems,  documentation 
provides  a  communications  medium  for  people.    It  is  prepared  to  provide 
information  on  why  computer  programs  were  prepared,  how  they  are  to  be 
designed,  what  the  systems  are  expected  to  do,  how  to  interpret  processing  results, 
how  systems  are  to  be  operated,  and  how  they  are  constructed  so  that  they  may  be 
used  again,  modified,  extended,  and  used  by  others.    Documentation  poses  a  host  of 
problems . 

What  are  some  of  the  documentation  problems? 

The  producer  of  documentation  is  faced  with  a  host  of  technical  problems. 
Documentation  serves  as  a  communications  medium  between  a  variety  of  people 
during  the  development  and  operation  of  a  software  system.    Various  document 
types,  addressing  different  audiences,  must  be  consistent  with  one  another  and 
integrated  into  an  overall  management  methodology.    Documents  must  be  correct 
at  each  instant  of  time  and  at  the  same  time  must  incorporate  changes,  must  be 
easy  to  update,  and  must  be  available  when  needed.    Documents  must  be  easy  to 
use.    With  all  these  constraints,  documents  must  be  producible  on  a  timely,  cost- 
effective  bases. 

Analyses  of  system  problems  have  surfaced  shortcomings  directly  attributable  to 
documentation,  or  the  lack  of  it: 

Millions  of  dollars  have  been  wasted  because  of  poor  user  requirements 
specifications , 

Systems  were  not  usable  because  of  lack  of  system  documentation. 

Systems  were  found  to  be  not  maintainable  because  of  lack  of  system 
documentation. 

Funding  for  needed  documentation  was  not  provided. 

Also,  some  of  the  problems  related  to  documentation  can  be  traced  to  lack  of 
management  interest,  support,  and  control  related  to  software  documentation. 

and  so  on  .  .  . 

Why  do  we  need  guidelines? 

It  has  been  shown  that  intelligent  use  of  guidelines  can  provide  great  economic  and 
social  benefits,  and  can  solve  major  problems  in  systems  development,  operation, 
maintenance,  and  re-use. 

Similarly  it  has  been  shown  that  lack  of  guidance  has  led  to  waste  of  millions  of 
dollars,  time,  and  resources. 

Why  are  FIPS  software  documentation  guidelines  useful?    They  provide  for 
generally  understandable  communications  media  which  support  project 
management,  product  development,  operations  and  maintenance,  transfer  and  re- 
usbility  of  computer  programs.    Thus  guidelines  can  save  both  money  and  time  in 
all  these  efforts. 

Why  do  we  have  this  workshop? 

I  now  would  like  to  review  the  rationale  for  this  workshop: 
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Existing  Information 


There  are  many  guidelines  and  standards  in  existence  which  have  a  bearing  on 
software  documentation.    They  were  developed  by  professional  organizations,  the 
American  National  Standards  Institute,  government  organizations,  and  the 
International  Standards  Organization,  to  name  a  few. 

Many  software  users  are  not  familiar  with  these  guidelines  and  standards,  but  users 
need  to  know  about  their  existence.    We  will  discuss  some  of  these  existing 
standards  and  guidelines  today. 

Knowledge  about  guidelines  alone,  however,  is  not  enough.    Users  need  to  know  how 
to  use  guidelines,  and  use  them  intelligently.    In  some  areas  there  is  a  lack  of 
guidelines  and  new  ones  may  need  to  be  developed.    In  other  areas  there  is  an 
overabundance  of  guidelines  which  often  conflict  with  one  another;  here  direction 
needs  to  be  provided  to  decide  which  guideline  should  be  used. 

We  will  discuss  experiences  of  users  with  some  of  the  guidelines,  discuss  pitfalls  in 
application,  misuse  as  well  as  useful  experiences. 

New  Guidance 

There  will  be  need  for  new  guidelines.    Our  technology  is  expanding  rapidly  and  new 
guidelines  will  be  needed  to  save  money,  time,  and  human  resources,  and  to  provide 
proper  documentation  when  needed.    The  need  is  to  provide  high  quality  software 
systems,  based  on  quality  documentation.    The  need  is  to  eliminate  waste--and  to 
increase  productivity. 

Research  in  support  of  standards  development 

And  finally  there  is  need  to  do  preliminary  analyses  and  to  do  some  real  research, 
to  determine  needs,  impact  of  proposed  standards,  balance  costs  and  benefits,  and 
determine  development  priorities.    In  addition,  many  technical  problems  still  need 
solution. 

Therefore: 

As  we  discuss  software  documentation  guidelines  --  both  existing  and  proposed 
guidelines  --  we  should  --  individually  and  collectively,  authors,  moderators, 
discussants,  records,  and  all  other  participants  --  critically  review  the  presented 
papers  and  the  ensuing    discussions  and  ask  the  following  questions: 


In  connection  with  existing  standards  and  guidelines; 

Is  the  guideline  or  standard  discussed  useful;  can  it  be  improved?    How  can  it  be 
improved?    Can  we  cite  economic  or  other  benefits  of  its  use?    What  guidance  can 
be  given  to  users  to  make  it  more  applicable,  useful,  and  effective? 

In  connection  with  proposed  guidelines: 

Does  the  topic  under  discussion  have  elements  which  could  help  to  achieve  economic  or 
social  benefits?    What  would  these  benefits  be?  -  Should  a  guideline  be  developed? 
How  could  it  best  be  developed? 
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In  connection  with  applicable  research; 


What  analyses  should  be  performed  in  support  of  guideline  development? 
Who  should  perform  these  analyses:    What  results  are  expected? 

Charge  to  this  workshop: 

To  summarize  the  reason  for  the  workshop  --  and  the  charge  to  this  group: 

Considering  existing  documentation  guidel ines. let  us  make  specific  recommendations  on 
their  applicability,  use,  benefits,  and  possible  improvements,  including  advice  and 
suggestions  as  to  their  usability.    Let  us  make  recommendations  for  specific  changes, 
additions,  deletions. 

Considering  new  or  proposed  guidelines,  let  us  make  specific  recommendations  on  their 
applicability,  use,  benefits,  and  possible  improvements,  including  advice  and 
suggestions  as  to  their  usability.    Let  us  make  recommendations  for  specific  changes, 
additions,  deletions. 

Considering  new  or  proposed  guidelines,  let  us  identify  new  areas  where  they  might  be 
useful,  and  make  specific  recommendations  on  what,  how  and  when  t  )  document. 

Considering  analysis  and  research  let  us  identify  directions  for  research  which  might 
lead  to  new  approaches  to  software  documentation  and  make  specific  recommendations. 


It  is  hoped  that  this  workshop  will  be  the  beginning  of  a  series  of  steps  which  will 
lead  to  major  improvements  in  software  documentation.    This,  in  the  broader  context, 
should  eventually  lead  to  improvements  in  software  engineering  which  will  reduce  system 
costs  and  improve  system  quality  and  software  productivity  in  the  Federal  Government. 

Measured  on  a  larger  scale,  our  efforts  should  support  economic  progress  of  our 
industry,  improve  productivity,  and  support  our  national  growth  as  well  as  our 
international  commitments. 
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SESSION  A:    Applying  Documentation  Standards  -  Case  Studies 
Moderator:    Charles  H.  Dickson,  U.S.  Department  of  Agriculture 


The  papers  highlight  various  problems  encountered  by  software  groups  both  inside  and  outside 
the  Federal  government  as  they  have  attempted  to  cope  with  the  array  of  presently  existing 
software  documentation  standards. 
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NBS  FIPS  Software  Documentation  Workshop,  March  3,  1982 


User  Experience  and  Compatibility  in  Documentation  Standards 

A  Summary 

Betty  F.  Maskewitz 

Engineering  Physics  Information  Centers  (EPIC) 
Oak  Ridge  National  Laboratory  (ORNL) 

This  paper  reviews  existing  guidelines  for  documentation  of  scientific 
computer  programs  or  data  libraries  and  outlines  the  essential  elements  for 
facilitating  exchange  of  the  software.    Selected  case  studies  will  be  made 
in  which  accepted  standards  were  followed  from  the  programming  stage  through 
documentation,  and  an  analysis  of  user  experience. 

Keywords:    Documentation  standards;  Software  compatibility;  User  experience. 


1.  INTRODUCTION 

The  problem  of  computer  software  inter- 
change is  one  that  has  long  plagued  computer 
users.    Converting  a  computer  program  from 
one  computing  environment  to  another  is 
frustrating,  tedious,  time  consuming  and 
costly.    The  problem  is  compounded  when 
documentation  is  inadequate  or  unavailable. 
Early  informal  efforts  by  individuals  who 
recognized  the  importance  of  software  docu- 
mentation to  facilitate  exchange  resulted  in 
the  formation  of  several  standards  groups 
under  varied  sponsorship.    One  such  group, 
developed  under  the  auspices  of  the  American 
Nuclear  Society's  (ANS)  Mathematics  and 
Computation  Division  (M&CD),  is  today  a  sub- 
committee (ANS-10)  of  the  Society's  Stan- 
dards Committee.    This  standards  effort, 
aimed  at  scientific  computing  applications, 
is  the  one  with  which  I  have  been  most 
closely  associated.    Several  standards  to 
facilitate  interchange  were  developed  by 
ANS-10  over  the  last  20  years. 

In  the  early  1960s  we  were  very  cau- 
tious in  our  approach  to  standardization. 
The  name  we  adopted  (STICE)  has  long  lost 
its  identity,  but  we  pronounced  it  "sticky." 

"We  took  upon  standccrdization  effort 
as  a  two-edge  sword.    While  it  has 
great  potential  for  cutting  through 
costly  duplication^  it  has  equal 
potential  for  cutting  off  further 
development.     This  dilemma  is 
particularly  acute  in  the  area  of 
computing.     On  the  one  hand,  stan- 
dardization could  reduce  the  tre- 
mendous expenditures  of  money  and 
manpower  required  for  the  creation 
of  computer  programs  by  increasing 
the  utility  of  each  of  them.     On  the 
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other  handi  experimentation  with  many 
different  languages  and  systems  must 
he  permitted  and  encouraged  if  we  are 
to  close  the  gap  between  hardware 
development  and  our  ability  to  use 
it  effectively . 

"Docimentation,  however,  is  one  area 
in  which  recommendations  for  minimum 
standards  should  he  made.    In  the 
past 3  documentation  has  been  directed 
primarily  to  the  person  who  prepares 
input  for  the  program.    This  type  of 
documentation  does  permit  the  program 
to  he  used  effectively  at  the  origi- 
nating installation  but  is  generally 
not  sufficient  if  the  program  is  to 
be  used  by  others.    It  is  feasible, 
however,  for  documentation  to  be  of 
material  help  to  a  programmer  in 
another  installation  who  is  incor- 
porating the  program  into  a  new 
operational  environment.    To  this 
end  the  quantity  of  documentation 
must  he  increased  over  that  normally 
supplied.    It  should  certainly 
include  not  only  the  report  directed 
toward  the  user  but  also  source 
language  comments  and  installation 
reports. " 

The  above  premise,  part  of  the  foreword 
of  the  first  proposed  standard  promoted  by 
STICE,  appeared  in  the  first  draft  circu- 
lated for  comments. [1]    It  was  entitled, 
"A  Code  of  Good  Practices  for  the  Documen- 
tation of  Digital  Computer  Programs." 
Adopted  as  ANS-STD.  2-1967,  it  was  revised 
and  reissued  as  American  National  Standard 
ANSI  N413-1974  [2]  and  is  now  again  in  the 
revision  process.    During  this  same  period 
progress  was  also  made  in  parallel  comple- 
mentary standardization  efforts. 


2.    USER  EXPERIENCE  AND  COMPATIBILITY 

My  long  involvement  in  the  standardiza- 
tion process  has  had  profound  influence  on 
all  my  professional  activities.    The  ORNL 
Radiation  Shielding  Information  Center  (RSIC) 
has  always  treated  computing  technology  in 
its  subject  coverage  in  the  same  manner  as 
any  other  valid  technology,  insisting  that 
it  must  be  well  documented,  open  to  critical 
examination  and  to  modification,  and  avail- 
able for  general  use.    The  first  and  most 
important  criteria,  it  must  be  documented. 

RSIC  had  two  favorable  elements  in  pro- 
moting standardization:    a  specialized  user 
community  that  needed  RSIC's  technology 
resources  and  a  monthly  newsletter.  We've 
come  a  long  way.    The  examples  I've  chosen 
to  support  the  premise  that  standards  make 
a  difference  are  taken  from  the  RSIC 
experience. 

Monte  Carlo  methods  for  forecasting  the 
behavior  of  radiation  in  diffusing  through 
matter  has  been  used  as  a  research  tool 
since  the  advent  of  large  digital  computers. 
It  is  a  complex  tool,  and  its  use  is  more  an 
art  than  an  exact  science.    Human  judgment 
is  an  essential  element.    The  early  practi- 
tioners of  the  art  believed  it  impossible  to 
document.    Transmittal  to  other  than  the 
developers  followed  only  after  a  one-to-one 
apprenticeship  of  days  and/or  weeks. 

My  ORNL  division  invested  many  man- 
years  in  programming  Monte  Carlo  techniques 
in  what  was  meant  to  be  a  reactor  research 
tool.    Without  documentation,  the  end  result 
remained  unused  by  other  than  the  developers. 
Using  preliminary  drafts  of  a  set  of  guide- 
lines for  documentation  to  facilitate  ex- 
change (vintage  1963-1965),  the  developers 
were  encouraged  to  document  their  modular 
Monte  Carlo  code  system,  05R.    To  test  their 
efforts,  we  featured  05R  [3]  in  a  seminar- 
workshop  at  ORNL  in  1965  and,  by  invitation, 
at  the  OECD  Nuclear  Energy  Agency's  Computer 
Program  Library  at  Ispra,  Italy,  in  1966. 
The  international  radiation  transport  com- 
munity accepted  05R  as  the  Monte  Carlo  code 
to  use  for  at  least  10  years.    The  code 
package  was  disseminated  to  more  than  400 
requesters,  the  heaviest  action  in  RSIC  in 
the  late  1960s.    The  computing  technology 
was  obsoleted  by  later  development  in  1977. 
The  documentation  of  the  Monte  Carlo  pro- 
cesses is  still  requested. 

A  similar  experience  in  high  energy 
physics  can  be  cited  with  the  National 
Bureau  of  Standards  (NBS)  Center  for  Radia- 
tion Research's  Monte  Carlo  code  system  for 


electron  and  photon  transport.  Documented 
in  1968  using  available  guidelines,  [4]  a 
seminar-workshop  in  1959  with  53  attendees, 
disseminated  158  times  (1968-1982)  all  over 
the  world,  ETRAN  today  is  used  in  the  nature 
of  a  standard  in  its  area  of  application. 
It  has,  of  course,  been  modified  (code  and 
document)  many  times  in  early  usage,  less 
so  as  time  passed.    It  was  last  shipped  in 
February  1982. 

Another  example  of  standardized  software 
documentation  is  that  represented  by  the 
discrete  ordinates  codes  of  Los  Alamos 
National  Laboratory.    The  documentation  of 
the  two-dimensional,  multigroup,  transport 
code  systems,  TRIPLET  [5]  and  TRIDENT  [6]  so 
explicitly  follow  early  ANS-10  guidelines 
as  to  be  a  prototype  of  the  standard.  The 
abstract,  the  theory,  the  guide  to  user 
application,  and  programming  information 
sections  are  each  directed  toward  a  specific 
audience.    Just  as  important,  standardized 
programming  practices  were  also  followed. 

Documentation,  although  important,  is 
not  the  only  factor  in  facilitating  exchange 
of  computing  technology.    Programming  prac- 
tices, [7]  program  design  with  user  consider- 
ation [8]  in  mind,  verification,  and  ease  of 
modification  are  important  elements  and  each 
can  be  improved  through  standard  practices. 
Standards  can  be  used  to  promote  effective 
utilization  and  enhance  reliability  of 
computer  programs  in  any  application  area, 
not  just  the  scientific. 

There  exist  several  sets  of  guidelines 
for  the  documentation  of  scientific  computer 
programs.    Good  documentation  promotes  under- 
standing, reduces  duplication  of  effort, 
eases  conversion  to  different  computer 
environments  and  aids  modification  for  ex- 
tended applications.    Good  documentation  is 
needed  to  facilitate  effective  usage,  trans- 
fer, conversion,  and  modification  of  com- 
puter programs.    Good  documentation  is 
essential  for  implementation  and  effective 
use  of  programs  within  installations  other 
than  those  in  which  they  are  developed. 

I  was  recently  involved  in  the  valida- 
tion of  energy-economy  models  used  in 
predictive  calculations  for  the  DOE  Energy 
Information  Administration's  annual  report 
to  congress.    As  usually  happens,  the  first 
serious  problem  area  was  related  to  inade- 
quate or  nonavailability  of  documentation 
of  the  models.    I  was  asked,  at  some  stage 
of  the  validation  effort,  to  review  the 
several  documentation  standards  efforts  and 
suggest  guidelines  for  the  modelers  to 
f  0 1 1  ow . 


A  brief  comparative  review  was  made  of 
FIPS  PUB- 38,  "Federal  Information  Processing 
Standards  (PIPS)"  publication  of  February 
1976  entitled  "Guidelines  for  Documentation 
of  Computer  Programs  and  Automated  Data 
Systems"  and  ANS-10. 3/ANSI  N413-1974  "Stan- 
dard on  Guidelines  for  the  Documentation  of 
Computer  Programs"  and  its  1982  revision; 
and  ANSI/ANS-10. 5-1979,  "Guidelines  for  Con- 
sidering User  Needs  in  Computer  Program 
Development."    The  result  of  the  study  is 
appended. 

The  RSIC  experience  in  promoting  soft- 
ware standards  points  to  several  conclusions. 
The  first  of  which  suggests  that  we  can  and 
should  cooperate  in  this  important  task. 


3.  CONCLUSIONS 

Either  or  all  of  the  aforementioned 
guidelines,  if  followed  reasonably  closely, 
would  produce  better  documentation.  The 
fault,  then,  is  not  in  the  guidelines  but 
in  the  failure  of  code  developers  to  con- 
sider documentation  as  an  important  function. 
Code  development  evolves  in  phases  from  the 
time  that  an  idea  to  create  the  software 
occurs  through  the  time  that  that  software 
produces  the  required  output  and,  beyond 
that,  to  the  time  that  there  is  extensive 
usage  in  a  wide  variety  of  applications 
with  resulting  feedback  to  a  software  main- 
tenance group.    Four  phases  apply  to  the 
software  life  cycle:    initiation,  develop- 
ment, operation,  and  continuing  maintenance 
until  it  is  no  longer  used.    The  documenta- 
tion of  the  software  should  evolve  through 
the  same  phases.    If  the  documentation 
develops  as  the  code  develops,  draft  copies 
should  be  available  during  the  test  stage 
and  continue  through  the  operation  and 
maintenance  phases,  updated  as  needed.  By 
the  time  the  code  will  have  achieved 
"public  domain"  status,  the  documentation 
should  be  current.    It  follows  that  any 
contract  let  for  code  development  should 
include  as  a  vital  part  of  the  action  plan 
the  necessity  to  document  the  code 
development. 

Documentation  preparation,  therefore, 
should  be  treated  as  a  continuing  effort, 
evolving  from  preliminary  draft  through 
changes  and  reviews,  through  the  documenta- 
tion and  software  delivery,  and  to  subse- 
quent updates  indicated  by  user  feedback. 

There  are  at  least  four  essential 
parts  to  the  documentation  of  computer  code 
systems:    1)  the  program  abstract,  directed 
to  the  potential  user;  2)  the  application 


information  (user's  manual),  directed  to 
the  individual  concerned  with  the  execution 
of  the  program  to  obtain  results  for  his 
application;  3)  the  problem  or  function 
definition,  directed  to  those  concerned 
with  the  mathematical  models  and  algorithms 
employed  in  the  program;  and  4)  the  program- 
ming information,  directed  to  the  programmer 
concerned  with  the  implementation,  mainte- 
nance, and  modification  of  the  program. 

The  above,  which  should  outline  the 
content  of  the  documentation,  can  be  one 
all-inclusive  document  for  a  simple  code 
system  or  up  to  four  separate  volumes  for 
a  complex  system. 

A  sampling  was  made  of  the  experience 
of  an  information  analysis  center  (RSIC) 
which  treats  scientific  computing  technology 
in  the  same  manner  as  any  other  valid  scien- 
tific information,  i.e.,  open  to  critical 
examination,  widely  used,  frequently  changed 
to  reflect  the  changing  state  of  the  art, 
and  documented  following  published  standards. 
The  20-year  history  of  the  center  in  which 
the  use  of  documentation  and  other  standards 
were  vigorously  promoted  records  tangible 
evidence  that  the  use  of  standards  makes  a 
significant  difference  in  utilization  and 
increased  usage  serves  to  advance  the  state 
of  the  art. 

Selected  case  studies  were  presented 
in  which  it  was  obvious  that  standards  were 
followed  in  the  original  documentation  of 
the  code  development.    It  has  been  amply 
demonstrated  that  compatibility  with  modern 
software  technology  and  methodology  can  be 
maintained  by  frequent  documentation  and 
program  review,  and  resultant  updates  made 
through  the  "open  code/data  package"  concept 
described  below. 

Validation  of  any  computing  technology 
in  a  rapidly  changing  technological  environ- 
ment, is  a  continuous  process  and  necessar- 
ily requires  the  dynamic  interaction  of 
several  elements.    RSIC  leaders  have  pio- 
neered in  related  work  and  have  been  cited 
by  their  peers  as  having  materially  ad- 
vanced the  state  of  the  art  in  the  field  by 
developing  and  following  procedures  and 
techniques  designed  to  promote  a  standard- 
ized product  with  consequent  quality 
assurance.    The  "open  code/data  package" 
has  been  the  concept  through  which  RSIC  has 
promoted  standards.    "Open"  codes  (models/ 
computer  programs)  and  data  libraries  are 
those  which  become  wel 1 -documented,  closely 
scrutinized  by  the  industry  at  large, 
widely  used  and  frequently  modified,  i.e., 
open  to  the  same  critical  examination  given 


to  any  valid  scientific  information.  The 
concept  is  realized  when  the  developer,  the 
center,  and  the  user  collaborate  to  assess 
and  improve  the  state  of  the  art.  Positive 
feedback  and  this  close  inter-relationship 
results  in  changes  that  are  reflected  in 
the  "open  code/data  package"  as  updated 
(improved)  versions.    Dissemination  of  the 
packages  with  a  training  and  consultant 
service  promotes  wider  usage  with  consequent 
feedback  to  the  Center.    As  long  as  there  is 
an  interest  in  the  problem  area,  the  code 
package  continues  to  grow  in  use  and  effec- 
tiveness.   The  concept  serves  to  promote 
standardized  methods  with  consequent  quality 
assurance. 

The  process  begins  and  ends  with 
documentation  standards. 
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APPENDIX 


GUIDELINES  FOR  DOCUMENTATION 
TO  FACILITATE  INTERCHANGE  OF  DIGITAL  COMPUTER  PROGRAMS 


Betty  F.  Maskewitz 
Oak  Ridge  National  Laboratory  (ORNL) 


There  exist  several  sets  of  guide- 
lines for  the  documentation  of  computer 
programs.    Good  documentation  promotes 
understanding,  reduces  duplication  of 
effort,  eases  conversion  to  different 
computer  environments  and  aids  modifi- 
cation for  extended  applications.  Good 
documentation  is  needed  to  facilitate 
effective  usage,  transfer,  conversion, 
and  modification  of  computer  programs. 
Good  documentation  is  essential  for 
implementation  and  effective  use  of 
programs  within  installations  other 
than  those  in  which  they  are  developed. 

The  following  definitions  are  ap- 
plicable specifically  to  this  memoran- 
dum:   (1)  Algorithm.    A  well-defined 
procedure  or  process  for  the  solution 
of  a  problem  to  a  specified  degree  of 
accuracy  in  a  finite  number  of  steps. 
(2)  Benchmark  Problem.    Both  a  well- 
defined  problem  and  corresponding  solu- 
tion, endorsed  by  a  professional  society 
or  other  recognized  technical  entity  that 
can  serve  as  a  validated  reference.  (3) 
External  Data  Files.    The  data  files 
which  exist  prior  to  execution  or  after 
completion  of  a  computer  run.    (4)  Com- 
puter Installation  Environment.  The 
computer  hardware  devices  and  software 
support  that  are  utilized  by  a  computer 
program  and  affect  its  design  and  opera- 
tion.   (5)  Code  Package.    All  computer- 
readable  and  printed  material  necessary 
for  transmitting  and  implementing  a  pro- 
gram (or  model)  in  a  different  computer 
installation  environment  than  that  in 
which  it  was  designed. 

A.    DOCUMENTATION  GUIDELINES 

There  are  at  least  four  essential 
parts  to  the  documentation  of  computer 
code  systems:    1)  the  program  abstract, 
directed  to  the  potential  user;  2)  the 
application  information  (user's  man- 
ual), directed  to  the  individual  con- 
cerned with  the  execution  of  the  program 
to  obtain  results  for  his  application; 
3)  the  problem  or  function  definition, 
directed  to  those  concerned  with  the 


mathematical  models  and  algorithms  em- 
ployed in  the  program;  and  4)  the  pro- 
gramming information,  directed  to  the 
programmer  concerned  with  the  implemen- 
tation, maintenance,  and  modification  of 
the  program. 

The  above,  which  should  outline  the 
content  of  the  documentation,  can  be  one 
all-inclusive  document  for  a  simple  code 
system  or  up  to  four  separate  volumes  for 
a  complex  system. 

1 .    Computer  Program  (Model)  Abstract 

The  abstract  provides  a  summary  of 
the  capabilities  of  a  computer  program 
(model),  or  code  package,  and  the  require- 
ments for  implementation.    The  abstract 
should  be  concise,  but  convey  sufficient 
information  to  permit  the  reader  to  assess 
the  applicability  of  the  program  to  his 
needs  and  the  effort  required  to  make  it 
operational.    It  should  include  a  brief 
statement  of:    (a)  program  identification: 
name,  descriptive  title,  and  information 
necessary  to  uniquely  define  the  current 
version;  (b)  description  of  problem  or 
function;  (c)  method  of  solution:  math- 
ematical techniques,  procedures,  and  nu- 
merical algorithms;  (d)  auxiliary  routines 
or  external  data  files  required  for  utili- 
zation; (e)  limitations  imposed  by  the 
mathematical  model  or  computer  facilities; 
(f)  identification  of  computer(s)  on  which 
the  program  has  been  successfully  execu- 
ted; (g)  information  to  enable  a  user  to 
estimate  computer  execution  time  for  a 
typical  application;  (h)  programming  lan- 
guages; (i)  operation  systems:  software 
system  and  versions  utilized;  (j)  a  list 
of  the  computer  hardware  required  for 
utilization;  (k)  the  names  and  addresses 
of  the  individual (s)  or  group  currently 
responsible  for  the  code  model  package; 
(1)  references;  (m)  material  available: 
the  contents  of  the  code  package  and  the 
procedure  for  obtaining  this  material. 
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2.    Application  Information  (user's 
Manual ) 

The  User's  Manual  should  be  suffi- 
ciently detailed  to  permit  effective  use 
of  the  program  (model)  and  yet  concise 
enough  to  serve  as  a  referral  document 
for  preparation  of  input  data  and  in- 
terpretation of  results.    It  should  in- 
clude general  description  including  a 
synopsis  that  conveys  the  nature  of  the 
problem  solved,  defines  the  processing 
tasks  performed,  and  describes  the 
methods  and  procedures  employed.  It 
would  be  useful  to  schematically  display 
the  flow  of  the  calculations. 

2.1.  Program  Considerations.  De- 
tailed  information  should  be  given  on  the 
following:    (a)  function  of  each  major 
program  option;  (b)  alternate  paths  which 
may  be  dynamically  selected  by  the  program 
from  tests  on  calculated  results;  (c)  re- 
strictions on  the  range  of  values  of  var- 
iables; (d)  the  dimensions  of  data  arrays; 
(e)  dependence  of  data  storage  require- 
ments on  problem  input  parameters;  (f)  the 
values  assigned  to  constants  built  into 
the  program;  (g)  restart  and  recovery  pro- 
cedures; (h)  programmed  diagnostics  and 
their  causes;  (i)  any  man-machine  inter- 
actions; (j)  information  to  estimate  exe- 
cution time;  (k)  any  special  forms  of 
output;  e.g.,  microfilm,  cathode  ray  tube 
display. 

2.2.  External  Data  Files.  External 
data  files  should  be  described  as  follows: 

(a)  outline  the  general  contents  and  or- 
ganization of  each  external  data  file; 

(b)  relate  the  usage  of  data  files  to 
the  execution  of  the  program;  (c)  refer- 
ence available  auxiliary  programs  which 
create,  modify,  or  edit  these  files; 

(d)  reference  sources  of  fixed  or  perma- 
ent  -data. 

2.3.  Input  Data.    General  and  spe- 
cific considerations  should  be  given  to 
input  data.    Generally,  one  should  de- 
scribe:   (a)  special  input  techniques 
and  requirements;  e.g.,  blank  field 
treatment,  order  of  items,  field  de- 
lineation; (b)  the  handling  of  consec- 
utive cases  (giving  conditions  of  data 
retention  or  reinitialization  for  the 
next  case);  (c)  the  general  conventions 
governing  default  values. 

Specifically,  for  each  input  vari- 
able one  should  give  variable  name. 


description  or  definition,  format,  dimen- 
sional units  of  variable,  and  the  default 
value  if  appropriate. 

The  operating  system  control  commands 
(cards  or  statements)  required  to  execute 
the  program  should  be  given  with  an  indi- 
cation of  interdependence  with  input  op- 
tions and  date  files. 

2.4.  Output.    The  program  output 
should  be  described  with  relationships 
shown;  e.g.,  edited  output  to  input  op- 
tions and  output  to  appropriate  equations. 
Any  normalizations  of  results  should  be 
described  and  associated  dimensional  units 
listed. 

The  physical  problem  and  associated 
data  files  should  be  described  and  the 
input  data  and  results  presented. 

2.5.  Sample  Problems.  The  following 
should  be  considered  in  selecting  sample 
problems:  (a)  choose  a  benchmark  problem 
or  a  well-defined  example;  (b)  exercise  a 
large  portion  of  the  available  programmed 
options;  (c)  use  only  a  reasonable  amount 
of  computer  time. 

The  following  should  be  considered 
in  presenting  the  edited  output:    (a)  pro- 
vide representative  output  for  the  options 
exercised  (detailed  output  can  be  trans- 
mitted on  tape);  (b)  present  results  of 
key  items  in  concise  form;  (c)  indicate 
precision  of  results. 

Report  eomputeif^  execution  time  for  the 
sample  problems  giving  central  processor 
time,  peripheral  processor  time  and  elapsed 
(clock)  time,  and  channel  use  applicable 
and  available. 

3.    Problem  of  Function  Definition 

The  problem  or  function  definition 
information  should  convey  a  thorough  under- 
standing of  the  theoretical  and  mathemati- 
cal foundations,  referencing  the  open  lit- 
erature where  appropriate.    It  should  de- 
fine the  problems  solved,  describe  the 
mathematical  model  employed,  and  document 
the  computational  algorithms  and  numerical 
techniques  implemented  in  the  program 
(model).    It  should  specifically  include  a 
comprehensive  description  of  the  problem 
solved  or  of  the  data  processing  functions 
performed.    The  description  of  the  physical 
theory  in  terms  of  a  mathematical  model 
should  be  reasonably  self-contained. 
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Sources  for  the  model  and  the  mathemati- 
cal formulations  should  be  referenced. 
Sufficient  detail  is  needed  to  permit  a 
user  to  judge  the  suitability  of  the 
model  for  application  to  a  particular 
situation.    Assumptions  should  be  noted 
and  information  given  about  limitations. 

3.1.  Algorithms  and  Numerical 
Techniques.    The  computational  algorithms 
used  to  obtain  numerical  solutions  of 
mathematical  equations  should  be  de- 
scribed and  references  to  algorithms 

and  numerical  techniques  provided.  The 
precision  of  results  obtained  by  impor- 
tant algorithms  and  any  known  dependence 
on  the  particular  computer  facility 
should  be  described.    Unusual  features 
of  techniques  used  should  be  described. 
For  iterative  solutions,  the  use  and 
interpretation  of  convergence  tests  and 
recommended  values  of  convergence  cri- 
teria should  be  included.    For  proba- 
bilistic solutions,  the  precision  of 
results  having  a  statistical  variance 
should  be  discussed. 

3.2.  Data  Sources.  Background 
information  about  source,  contents,  and 
use  of  data  libraries  should  be  provided. 

4.    Programming  Information 

The  programming  information  is 
directed  to  the  individual  responsible 
for  implementing  the  program  on  his 
computer,  modifying  or  extending  it  to 
meet  local  needs,  or  converting  it  to  a 
different  computer  environment. 

Reference  may  be  made  to  appropri- 
ate items  described  in  other  sections 
of  the  program  document.    Give  further 
information  as  necessary,  to  explain 
the  programming  details.    The  citing 
of  computer-produced  documentation  that 
is  generally  available  may  complement 
traditional  documentation.  Examples 
of  such  computer-produced  documentation 
are:    a  listing  of  the  source  program 
that  contains  carefully  composed  com- 
ment cards,  a  cross-reference  dictionary 
of  subroutine  names  and  entry  points, 
and  flowcharts  of  the  program  logic. 

4.1.    Source  Program.    The  source 
program  description  should  include: 
(a)  identification  of  the  source  lan- 
guage{s)  of  the  coding;  (b)  a  flowchart 
showing  the  overall  program  structure 
and  logic,  and  detailed  flowcharts 
where  appropriate;  and  (c)  an  indication 


of  known  areas  of  dependency  upon  the  local 
computer  installation  support  facilities. 

Detailed  information  should  be  given 
as  follows:    (a)  define  the  role  and  func- 
tion of  the  main  program  and  each  subpro- 
gram (identify  argument  lists  and  their 
use);  (b)  for  a  particular  subprogram, 
indicate  those  routines  which  call  it  and, 
in  turn,  those  subprograms  it  may  call; 
(c)  relate  the  problem  variables  and 
constants  to  the  program  mneomics;  (d)  de- 
scribe shared  storage  assignments;  e.g., 
COMMON  in  FORTRAN;  and  (e)  describe  in 
detail  the  functions  performed  by  machine- 
dependent  subprograms  that  are  unique  to 
this  program. 

4.2.  Data  Files.    The  computer-ori- 
ented details  of  temporary  and  external 
data  files  should  be  provided:    (a)  speci- 
fy the  names,  usage  (input,  output,  or 
scratch),  structure,  mode  and  data  elements 
of  each  data  file;  and  (b)  discuss  program 
procedures  related  to. the  use  and  mainte- 
nance of  data  libraries  and  files,  giving 
data  file  retention  and  allocation  require- 
ments. 

4.3.  Hardware  and  Software.  Logical 
devices  used  should  be  enumerated  and  the 
use  of  each  device  and  any  associated  data 
blocking  schemes  described.    The  contents 
and  format  of  the  information  resident  on 
each  device  should  be  identified. 

The  computer  installation  environment 
in  which  the  model  is  normally  executed 
should  be  described  as  follows:    (a)  list 
the  machine  configurations  on  which  the 
model  has  been  tested  successfully;  (b) 
enumerate  the  main  memory  storage  require- 
ments, the  amount  and  type  of  auxiliary 
storage  (drum,  disk,  data  cell,  tapes)  and 
the  peripheral  equipment  (punch,  printer, 
plotter);  (c)  identify  any  special  hardware 
utilized;  e.g.,  clock,  on-line  communication 
channel . 

In  addition,  the  software  requirer.ients 
should  be  given:    (a)  identify  the  operat- 
ing system,  language  processors,  and  asso- 
ciated subroutine  libraries  invoked  by  the 
model,  citing  the  manufacturer's  appropri- 
ate versions  and  releases;  (b)  describe 
known  deviations  from  the  manufacturer's 
supported  software  that  are  required  by  the 
model;  e.g.,  local  mathematical  and  utility 
routines,  and  other  installation-dependent 
software. 
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4.4.    Programming  Considerations. 
Certain  programming  considerations  are 
important  for  successful  implementation: 
(a)  explain  the  system-control  commands 
required  to  execute  the  program;  (b) 
document  the  overlay  or  segmentation 
scheme  if  one  is  used;  (c)  describe 
the  storage  allocation  and  data-manage- 
ment procedures;  indicate  the  problem- 
dependent  nature  of  the  memory  require- 
ments; discuss  program  alternatives 
which  affect  data  storage  and  use  of 
data  buffering;  e.g.,  variable  dimen- 
sioning; (d)  discuss  the  restart,  re- 
covery, and  successive  case  capability. 

B.  CODE  PACKAGE  TRANSMITTAL  FORMAT 

The  code  package  is  the  aggregate 
of  card  decks  and  printed  material  as- 
sociated with  a  computer  program  (model), 
including  an  abstract  of  the  complete 
code  package  for  publicizing  availa- 
bility.   The  package  should  include: 

1.  Computer-readable  material 
written  on  magnetic  tape  as  separate 
files:    (a)  source  (main)  program  in 
the  form  of  card  image  records;  (b) 
any  auxiliary  code  used  to  generate 
input  for  the  main  program  or  analyze 
results;  (c)  any  external  data  librar- 
ies; (d)  input  data  for  sample  prob- 
lem's); (e)  system  control  cards  for 
execution  of  the  program;  (f)  output 
from  running  the  sample  problems  in 
line-printer  format. 

2.  Printed  Materials:    (a)  master 
tape  list  describing  each  file  in  (a) 
and  how  each  is  written  on  tape;  (b) 
documentation  of  the  complete  code 
package;  (c)  abstract  of  the  code 
package  (in  standard  format)  for  pub- 
lication. 

C.  VERIFICATION/VALIDATION  RECORDS 

Initial  verification  of  the  code 
system  is  normally  done  by  the  code 
developers  and  the  results  documented 
in  the  original  report  (see  item  A). 
Validation  is  normally  a  separate 
effort,  independently  done  and  re- 
ported.   As  validation  results  be- 
come available,  they  should  also  be 
included  in  the  code  package,  as  de- 
fined in  item  B.    These  records  should 
include:    documentation  -  published 
results  of  findings,  audit  trail  on 
data  used,  and  record  of  experience 
gained  from  running  benchmark  or  other 
calculations. 


NBS  FIPS  Software  Documentation  Workshop. 
March  3,  1982 


Systems  Development  Methodology 
and  Documentation  Practices 


Louis  J.  O'Korn 


Manager,  Systems  Development 
Chemical  Abstracts  Service 


The  approach  Chemical  Abstracts  Service  (CAS)  has  taken  to  prepare  and 
manage  the  full  range  of  software  documentation  will  be  described.    For  each 
development  stage  this  presentation  will  summarize  the  deliverable  items  of 
documentation,  specific  standards  and  procedures  guiding  the  documentation 
process,  and  specific  tools  supporting  the  preparation  and  management  of 
documentation. 


1.  INTRODUCTION 


All  methodologies  are  based  on  the  assumption  that  you  can  analyze  a  process  and 
identify  a  consistent  set  of  tasks  that  must  be  performed  in  a  particular  order  to  com- 
plete the  process.    Similarly,  in  systems  development,  the  methodology  attempts  to  predict 
the  tasks  that  must  be  performed  to  design,  develop,  and  implement  a  computer  system.  All 
effective  systems  development  methodologies  recognize  that  there  are  actually  two  types  of 
activities  that  must  be  performed  to  build  and  operate  a  computer-based  system: 


0  Activities  to  create  the  proposed  system.    These  include  interviewing  users  about 
proposed  system  requirements,  documenting  objectives  and  constraints  of  the 
proposed  system,  designing  overall  system  flow  for  the  proposed  system,  coding  and 
testing  programs,  and  so  forth. 


0  Activities  to  manage  the  system  building  process.    These  include  tasks  for  plan- 
ning, organizing,  and  controlling  systems  development  projects. 


The  Chemical  Abstracts  Service  (CAS)  systems  development  methodology  draws  from  both 
these  areas.    This  paper  identifies  the  tasks  required  to  build  a  system.    It  describes 
the  phases  of  the  CAS  system  life  cycle,  specific  deliverables,  and  guidelines  for  each 
subphase.    The  project  management  policies,  procedures,  and  deliverables  required  to  plan, 
organize,  and  control  the  project  activities  necessary  for  building  computer-based  systems 
are  not  addressed  in  this  paper. 
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2.    SYSTEM  LIFE  CYCLE 


At  CAS,  system  life  cycle  activity  is  described  as  fitting  into  one  of  four  broad 
phases:    System  Initiation,  System  Design  and  Development,  System  Implementation,  and 
System  Operation. 


The  objectives  of  the  System  Initiation  phase  are  to  identify  the  purpose  and 
description  of  the  system  and  the  needs  for  development  resources,  to  fully  document  user 
requirements,  to  generate  a  general  approach  for  the  proposed  system,  to  study  alternate 
design  strategies,  and  to  recommend  the  best  approach  for  the  development  of  a  particular 
system.    This  may  involve  breaking  the  system  into  individual  components  or  subsystems 
each  of  which  would  follow  the  system  life  cycle. 


The  next  step,  System  Design  and  Development,  resolves  all  design  features  of  the 
proposed  system.    To  do  so,  all  input,  output,  data  base  and  internal  processing  aspects 
of  the  design  are  developed  by  the  project  team,  technically  reviewed  within  Research  & 
Development  (R&D)  and  reviewed  by  operations  and  user  personnel.    Once  this  review  is 
completed,  all  approved  features  are  ready  for  development  and  are  not  subject  to  further 
design  modification  without  formal  review  and  approval  at  the  design  changes.    The  next 
objective  of  this  phase  is  to  develop  the  detailed  design  and  to  transform  the  design  into 
functional  system  components  through  program  design,  coding,  and  testing. 


The  third  phase  of  the  system  life  cycle  is  System  Implementation,  which  includes 
preparing  a  system  test  plan,  conversion  plans,  and  user  manuals,  conducting  the  system 
test,  performing  necessary  conversions,  releasing  the  system  to  data  processing  opera- 
tions, creating  live  files,  training  users,  and  beginning  operations.    The  final  objective 
of  this  phase  is  to  secure  formal  acceptance  of  the  new  system  from  the  user  group. 


Finally,  during  System  Operation,  the  objective  is  to  maintain  an  efficient  operation 
of  the  system,  evaluate  it,  and  make  changes  as  additional  requirements  are  identified. 


While  these  four  phases  are  useful  in  broadly  visualizing  a  project,  they  are  too 
general  to  serve  as  a  basis  for  planning,  scheduling  and  controlling  the  work  effort. 
They  are  further  divided  into  a  number  of  subphase: 

Phase  1  -  System  Initiation 

Project  Initiation 

User  Requirements  Definition 

System  Definition 
Phase  2  -  System  Design  And  Development 

Preliminary  Design 

Detail  Design 
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Program  Development 
Phase  3  -  System  Implementation 

Implementation  Planning 
System  Testing 
Operations  Start-Up 
System  Acceptance 
Phase  4  -  System  Operation 


3.    SYSTEM  INITIATION 


3.1    Project  Initiation 


Activity  in  this  subphase  is  directed  toward  translating  a  requested  project  into  a 
brief  Project  Initiation  Description.    Prepared  by  the  Development  Project  Manager  and 
system  requestor,  this  description  gives  the  name  of  the  project  and  the  user  departments 
concerned  and  details  the  project's  purpose,  scope,  benefits,  dependencies,  background, 
preliminary  development  forecasts,  and  schedules. 


If  the  Project  Initiation  Description  is  approved  by  R&D  and  the  requesting  division 
management,  a  project  then  enters  the  User  Requirements  Definition  subphase.    When  a 
proposed  system  is  intended  to  supplement  or  replace  an  existing  system  --  either  manual 
or  automated  --  the  project  team  begins  by  reviewing  the  operation  of  the  current  system 
and  assessing  its  merits  and  shortcomings.    Activity  then  focuses  on  determining  the 
users'  requirements  for  the  new  system,  working  closely  with  the  user  staff.    The  results 
are  rigorously  documented  to  guide  subsequent  design  and  development  tasks. 


3.2    User  Requirements  Definition 


The  User  Requirements  Document  represents  the  key  input  to  the  subsequent  design 
stage  because  it  is  a  definitive  statement  of  the  functions  to  be  performed  and  outputs  to 
be  delivered  by  the  system  as  seen  by  the  user.    Essentially,  it  is  a  playback:  the  result 
of  considerable  dialogue  between  the  analyst  and  the  user  regarding  the  functional 
specifications  of  the  system.    It  is  important  to  note  that  the  user  can  be  the  eventual 
system  user,  a  user-appointed  representative,  a  management-appointed  task  force,  or  a  new 
venture  team;  the  specific  approach  is  determined  on  a  project-by-project  basis. 

^ 

The  User  Requirements  Document  includes  an  elaboration  of  data  element  requirements, 
identification  and  description  of  required  algorithms,  clarification  of  policy  with  its 
known  impact  and  implications,  and  definitions  of  important  concepts.    It  includes  func- 
tional flows  only  as  needed  to  illustrate  the  above  material  and  clarify  interfaces  with 
existing  systems.    Generally,  this  document  will  be  co-authored  by  the  analyst  and  the 
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user,  or  a  user  representative,  and  will  be  subject  to  review  and  approval  by  the  user  and 
R&D  management. 


3.3    System  Definition 


Once  the  user  requirements  are  approved,  the  system  enters  the  System  Definition 
subphase,  where  the  user  requirements  are  used  to  prepare  a  general  design  of  the  new 
system.    The  project  team  identifies  and  evaluates  as  many  design  alternatives  as  practi- 
cal while  ensuring  that  enough  alternatives  have  been  considered  to  respond  to  critical 
needs.    Criteria  for  evaluating  the  alternatives  might  include  such  factors  as  anticipated 
system  benefits,  number  of  features  supported,  development  and  operation  costs,  or  techni- 
cal feasibility.    Before  proceeding  to  the  next  phase,  the  project  team  examines  the 
design  alternatives  and  the  criteria  used  to  make  a  final  evaluation  and  recommends  an 
approach  for  developing  the  system.    The  proposed  system  is  set  forth  in  a  System  Descrip- 
tion which  is  a  user-oriented  document  describing  a  proposed  approach,  alternative 
approches,  and  evaluation  criteria.    In  addition,  a  Cost/Benefit  Analysis  may  be  incor- 
porated into  the  System  Description  or  provided  as  a  separate  document.    The  proposed 
approaches  must  be  approved  by  R&D  and  user  management. 


4.    SYSTEM  DESIGN  AND  DEVELOPMENT 


4.1    Preliminary  Design 


Completion  of  the  three  System  Definition  subphases  marks  the  beginning  of  the  System 
Design  and  Development  phase.    Its  first  subphase.  Preliminary  Design,  focuses  on  design- 
ing and  documenting  a  preliminary  version  of  the  proposed  system.    The  tasks  performed 
during  this  subphase  include  preparation  of  an  overall  system  flow,  design  of  data  base 
content,  identification  of  the  various  subsystems,  creation  of  narrative  descriptions  of 
systems  operation,  and  description  of  system  inputs  and  outputs.    Most  importantly,  the 
preliminary  design  reflects  the  users'  processing  requirements  for  the  new  system.  The 
user  staff  is  involved  in  review  of  the  preliminary  design  to  interact  with  the  design 
process  and  ensure  all  requirements  are  included. 


The  project  leader  prepares  the  Preliminary  Design  Document,  which  includes  a  summary 
of  features,  system  architecture,  flow  and  narrative  function  descriptions,  data  defini- 
tion summary,  transaction  summary,  report  summary,  functional  responsibilities,  inter- 
faces, performance  estimates,  etc.    This  document  is  the  basis  for  a  technical  design 
review  within  R&D  to  ensure  soundness  of  the  technical  approach,  and  an  in-depth  func- 
tionality with  all  users  to  assure  that  all  requirements  are  satisfactorily  met.  Included 
as  separate  documents,  or  as  sections  in  the  Preliminary  Design  documentation,  are  updates 
to  the  User  Requirements  and  Cost/Benefit  Analysis.    The  Preliminary  Design  requires  the 
approval  of  R&D  and  user  management,  and  provides  guidelines  for  subsequent  technical 
development  in  the  Detail  Design  subphase. 
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4.2    Detail  Design 


Activity  in  this  subphase  is  devoted  to  designing  detailed  versions  of  every  systems 
component  identified  in  the  preceding  subphase.    Major  tasks  include  preparing  and 
documenting  the  detailed  report  layouts,  designing  all  input  forms  and  screens,  identify- 
ing the  final  data  base  structure  and  content,  designing  controls  for  all  manual  and 
computerized  aspects  of  the  operation,  file  backup  and  recovery  procedures,  data  entry 
procedures,  online  dialogs,  etc.    Included  as  separate  documents  or  as  separate  sections 
in  the  Detailed  Design  documentation,  are  updates  to  the  User  Requirements  and 
Cost/Benefit  Analysis. 


The  entire  system  features  reflected  in  Detailed  Design  are  now  intensively  reviewed 
by  the  system  users.    This  user  review  marks  a  major  milestone  in  the  project,  because  all 
design  elements  approved  here  will  become  permanent  features  of  the  system.    Once  all  the 
problems  have  been  resolved,  changes  in  design  during  subsequent  subphases  will  be  for- 
mally documented  and  require  final  approval  by  R&D  and  the  user  management.    If  during  the 
Preliminary  or  Detailed  Design  subphase  a  serious  design  flaw  is  identified,  it  may  be 
necessary  to  recycle  through  various  subphases  to  reconsider  aspects  of  the  approach 
taken. 


4.3    Program  Development 


It  is  essential  that  application  programs  be  designed  to  take  maximum  advantage  of 
sophisticated  hardware,  software,  systems  and  capabilities.    In  this  subphase,  the  struc- 
ture of  schedules,  programs,  and  modules  is  developed,  documented,  and  thoroughly  reviewed 
by  qualified  technical  personnel.    Program  design  produces  program  structure  which  is 
reviewed  through  walk-throughs.    Program  structure  is  converted  into  functional  components 
through  program  design,  coding,  testing,  and  documentation.    Programming  is  performed  in 
accordance  with  corporate  standards  and  policies.    During  testing,  emphasis  is  placed  on 
rigorous  preparation  of  a  test  plan  describing  all  anticipated  program  responses  to  test 
situations,  and  when  testing  commences,  test  results  will  be  compared  to  these  test  plan 
predictions,  thus  providing  an  objective  measurement  of  requirement  delivery.    All  test 
results  will  be  thoroughly  reviewed  to  ensure  that  system  components  are  operating  satis- 
factorily.   This  subphase  produces  a  completed  operational  program,  program  documentation, 
and  operations  documentation. 


5.    SYSTEM  IMPLEMENTATION 


5.1    Implementation  Planning 


The  System  Design  and  Development  phase  and  System  Implementation  phase  overlap  at 
this  point  in  the  development  cycle.    Implementation  Planning  begins  immediately  after 
completion  of  the  Detailed  Design  subphase  and  runs  parallel  to  the  Program  Development 
subphase.    The  subphases  overlap  in  this  way  so  implementation  can  begin  immediately  upon 
completion  of  program  testing.    Included  in  this  subphase  are  tasks  to  develop  detailed 
conversion  plans,  system  testing  plan,  training  schedules,  and  supporting  materials. 
Tasks  are  also  performed  to  develop  many  of  the  user  manual  materials  for  subsequent 
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implementation  training  and  system  operation.  During  their  review  of  these  products,  the 
users  are  required  to  commit  themselves  to  training  and  conversion  schedules  as  set  forth 
in  the  implementation  plans. 


5.2    System  Testing 


During  the  System  Testing  subphase,  tasks  are  performed  to  assemble  programs  into 
subsystems  and  to  integrate  these  subsystems  into  a  working  system.    Work  begins  with  the 
creation  of  extensive  test  scenarios  and  test  data  is  then  prepared  to  simulate  these 
situations.    Operations  Documentation  is  compiled,  reviewed  and  finalized.    The  systems 
test  is  conducted  in  accordance  with  the  test  plan.    As  with  the  program  test,  system  test 
results  are  compared  with  the  test  plan  predictions  to  ensure  that  the  system  is  operating 
properly.    As  part  of  the  systems  test,  the  users  conduct  an  acceptance  test  to  verify 
that  their  specifications  have  been  met. 


5.3    Operations  Start-Up 


This  subphase  marks  the  transition  of  the  system  from  "in  development"  to  "opera- 
tional" status.    Here,  tasks  are  performed  to  finalize  operations  documentation,  data 
entry  documentation,  user  manuals,  schedules,  etc.    All  documentation  is  reviewed  with 
appropriate  user/operations  groups  to  facilitate  the  turnover  and  start-up  processes. 
Various  user  and  operational  areas  certify  that  the  documentation  meets  company  standards 
and  that  the  system  is  ready  to  begin  routine  operation. 


Tasks  are  then  oerformed  to  finalize  implementation  schedules.  The  users  are  given 
manuals  describing  external  procedures,  and  are  thoroughly  trained  to  use  their  new  sys- 
tem.   Finally,  files  are  set  up  or  converted  to  support  ongoing  system  operations. 


5.4    System  Acceptance 


After  a  system  becomes  operational,  the  project  team  is  responsible  for  monitoring 
operations  and  assisting  the  users  wherever  problems  are  encountered.    If  a  new  system  was 
developed  to  replace  an  older  system,  the  two  may  be  run  in  parallel  until  all  parties  are 
satisfied  that  the  new  system  is  functioning  correctly.    At  the  end  of  the  parallel  opera- 
tions and  before  the  old  system  is  retired,    users  are  "required  to  formally  certify  that 
their  training,  documentation,  and  the  new  system  itself  satisfy  the  original  require- 
ments.   At  this  stage,  all  project  documentation  is  transferred  into  permanent  storage  and 
an  evaluation  is  made  of  the  project  on  the  basis  of  observed  strengths  and  weaknesses. 


6.    SYSTEM  OPERATIONS 


With  the  acceptance  and  routine  operation  of  the  system,  staff  maintain  installed 
software  and  make  minor  enhancements  as  necessary.    Documents  produced  during  this  phase 
describe  problem  resolution  procedures  e.g.  abnormal  program  completions,  corrections 
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actions,  condition-causing  problems,  requests  and  documentations  for  minor  system  enhance- 
ments, and  documentation  of  program  module  changes. 


7.  SUMMARY 


There  is  a  wide  variety  of  documentation  produced  during  the  CAS  system  life  cycle. 
The  earlier  section  summerizes  activities  performed  and  key  deliverables  for  each  sub- 
phase. 


To  aid  the  staff  in  preparation  of  these  documentation  items,  each  item  has  suggested 
contents,  specific  staff  responsible  for  preparation,  and  specific  staff  responsible  for 
review  and  approval.    It  must  be  recognized  that  there  are  suggested  documentation  items 
to  identify  critical  documentation  requirements  and  achieve  a  consistent  CAS  scheme.  For 
a  particular  system,  the  specific  documentation  items  to  be  prepared  will  be  proposed  by 
the  project  leader,  and  the  documentation  package  may  require  additional  documentation 
items,  the  combination  of  several  of  these  items,  an  expansion  of  an  item,  change  in 
format,  etc. 


CAS  has  a  separate  operational  unit  responsible  for  the  administration  of  computer 
system  and  data  base  documentation  in  support  of  CAS  development,  maintenance,  and  opera- 
tional activities.    The  data  base  function  controls  the  authoritative  record  and  inventory 
of  CAS  files,  their  definition  and  interrelationships.    As  part  of  this  data  base  respon- 
sibility, this  unit's  services  include  registration  of  data  elements  and  data  sets, 
recovery  and  reorganization  of  system  files,  management  of  the  file  archiving  process, 
management  of  tape  and  disk  resources,  and  analysis  and  consultation  on  data  base  perfor- 
mance. 


The  computer  system  documentation  function  manages  the  master  record  of  computer 
system  and  program  documentation.    It  stores  the  complete  inventory  of  documentation, 
maintains  a  historical  change  record,  provides  reference  library  services,  processes  all 
program  changes,  and  controls  updates  to  production  software  libraries. 
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Experience  in  Application 
of 

Software  Documentation  Standards 

Wi 1 li am  Bryan 
Stan  Siegel 

CTEC,  Inc. 

This  paper  summarizes  the  authors'  recent  experience  applying  soft- 
ware documentation  standards  contained  in  MIL-STD-483,  MIL-STD-1679, 
and  DoD  STD  7935. 1-S  (and  its  non-DoD  counterpart  FIPS  PUB  38). 
Several  software  documentation  problem  areas  are  discussed.  One 
problem  area  is  redundancy  --  the  requirement  to  put  the  same  material 
(in  different  form  or  degree  of  detail)  in  two  or  more  documents  in 
the  same  set.    Not  only  does  this  redundancy  increase  project  costs 
and  lengthen  schedules,  it  also  greatly  complicates  the  life 
cycle  maintenance  of  the  documents.    A  second  problem  area  is  the 
telescoping  of  test  documents  in  FIPS  PUB  38  and  DoD  STD  7935. 1-S. 
In  these  two  standards,  test  procedures  and  test  plans  are  included 
in  the  same  document.    If  test  procedures  are  written  concurrently 
with  the  test  plan,  customer  modifications  to  the  test  plan  may 
partially  invalidate  the  test  procedures.    A  final  problem  area  is 
that  of  tailoring  software  documentation  requirements.  Software 
documentation  standards  should  permit  sufficient  tailoring  to  cope 
with  project  size  and  complexity  without  vitiating  the  documents. 
The  paper  includes  recommendations  for  improvements  to  software 
documentation  standards. 

Keywords:    Product  assurance;  Software  maintenance;  Testing; 
Traceabi 1 ity;  Visibility 


1.  INTRODUCTION 

The  past  few  years,  the  authors  have  performed  software  product  assurance  services 
for  both  in-house  and  external  software  development  projects.    Product  assurance 
entails,  in  our  view,  the  integrated  performance  of  the  following  four  disciplines: 

the  assessment  of  whether  a  software  product  conforms 
to  a  pre-specified  standard 

the  assessment  of  whether  a  software  product  logically 
follows  from  its  predecessor  software  products  and  is 
congruent  with  the  software  requirements 

the  assessment  of  whether  a  software  product  satisfies 
its  requirements  through  testing  in  a  live  or  nearly 
live  environment 

the  set  of  procedures  for  visibly,  traceably,  and 
formally  controlling  software  products  throughout  the 
software  life  cycle 

Performing  software  product  assurance  services  clearly  involves  the  use  of  software 
documentation  standards.    This  use  is  not  connected  with  the  actual  development  of 
software  and  its  associated  documents,  but  rather  is  concerned  with  the  utilization  of 
standards  as  a  tool  to  assess  the  successful  development  of  software  products. 


Quality  assurance  - 
Verification  &  validation  - 

Test  &  evaluation  - 

Configuration  management  - 
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Our  work  in  software  product  assurance  has  exposed  us  to  various  software 
documentation  standards  and  given  us  experience  in  their  use  as  product  assurance 
tools.    From  this  experience,  we  have  observed  a  number  of  problems  in  the  use  of  the 
software  documentation  standards.    In  this  paper,  we  address  three  of  these  problems  ~ 
(1)  redundancy  among  documents,  (2)  the  telescoping  of  test  documents,  and  (3)  the 
tailoring  of  software  documentation  requirements. 

In  the  balance  of  this  paper,  we  first  present  a  summary  of  our  recommendations 
regarding  software  documentation  standards.    Then  we  present  in  turn  each  of  the  three 
problems  stated  above.    We  close  the  paper  with  our  conclusions  based  on  our  analysis  of 
these  three  problems. 


2.    SUMMARY  RECOMMENDATIONS 

Based  upon  our  experience  with  various  software  documentation  standards,  we  make 
the  following  recommendations: 

a.  Eliminate  redundancy  among  the  documents  specified  by  a  software  documentation 
standard. 

b.  Stress  in  software  documentation  standards  the  need  for  continual  maintenance  of 
the  documents  produced. 

c.  Modify  FIPS  PUB  38  and  DoD  STD  7935. 1-S  to  specify  that  two  pre-test  documents, 
a  Test  Plan  and  Test  Procedures,  be  sequentially  produced. 

d.  Modify  software  documentation  standards  to  require  substantial  conformance  to 
their  format  and  content  specifications,  while  allowing  tailoring  and  scoping  of 
the  various  documents  to  match  project  size  and  complexity. 

3.    REDUNDANCY  AMONG  DOCUMENTS 

In  the  range  of  document  types  specified  by  FIPS  PUB  38  [1]  and  DoD  STD  7935. 1-S 
[2],  considerable  redundancy  is  specified.    The  existence  of  this  redundancy  is 
specifically  addressed  and  explained  in  both  standards.    One  reason  that  redundancy  is 
provided  is  to  make  the  documents  "stand-alone"  with  a  minimum  of  need  for 
cross-referencing  (FIPS  PUB  38,  paragraph  2.3;  DoD  STD  7935. 1-S,  paragraph  1.3.4).  That 
is,  the  basic  assumption  seems  to  be  made  that  the  reader  of  a  document  does  not  have 
ready  access  to  other  documents  produced  during  a  software  development  project,  and 
possibly  may  never  have  read  them.    In  this  circumstance,  each  document  must  be  as 
complete  and  detailed  as  is  possible,  and  must  accurately  reflect  the  state  of  the 
software  at  the  time  of  document  publication. 

This  form  of  redundancy  is  particularly  evident  in  the  Functional  Description  (FD), 
System/Subsystem  Specification  (SS),  and  Program  Specification  (PS)  sequence  found  in 
FIPS  PUB  38  and  DoD  STD  7935. 1-S  (see  Table  1).    In  the  content  guidelines  of  the  latter 
standard,  explicit  reference  is  made  to  paragraphs  in  preceding  documents  where  related 
material  is  found,  coupled  with  statements  that  "changes. . .from  the  next  higher  order 
[i.e.,  irmiediately  preceding]  document  will  be  explicitly  identified"  (see,  for  example, 
the  content  guidelines  for  paragraphs  2.2.1  and  2.2.2  in  Figure  3-04  on  page  3-33  of  DoD 
STD  7935. 1-S).    Such  statements  imply  that  a  given  document  (say,  an  FD)  may  or  may  not 
be  accurate  once  a  successor  document  (say,  an  SS)  has  been  published.    Where  and  to 
what  extent  a  predecessor  document  may  be  inaccurate  is  not  evident  to  a  reader.  A 
further  implication  here  is  that  a  given  document  is  not  maintained  once  a  successor 
document  is  published. 

It  should  be  noted  that  100%  redundancy  does  not  exist  among  these  documents.  Each 
document  has  certain  unique  sections  and  paragraphs  not  found  in  its  immediate 
predecessor.    Thus,  from  a  project  viewpoint,  the  documents  are  not  truly 
"stand-alone."    A  reader  wishing  to  become  familiar  with  a  project  should  read  the 
latest  document  in  this  sequence,  but  must  realize  that  he  is  not  accessing  all  the 
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Table  1.    Redundant  Paragraphs  Among  Several  Documents 
Specified  by  DoD  STD  7935. 1-S 


Functional 
Description 


System/Subsystem 
Specification 


Program 
Specification 


3.1.1 
3.1.2 
3.2 


2 

2.1 
2.2.1 


2 

2.1 

2.2.1 

2.2.2 

2.2 

2.3 

3 


2.2.2 


4 


2.2 
2.3 

3 


4.1 
4.2 
4.3 
4.4 


3.1 
3.2 
3.3 
3.4 
3.5 
4 


3.1 

3.2 
3.4 
3.5 

4 


4.3.1 
4.3.2 
4.3.3 


4.2 
4.3 
4.4 


pertinent  information  on  the  project.    Whether  this  process  is  satisfactory  to  him 
depends  upon  his  purpose  in  reading  about  the  project. 

This  redundancy  in  FIPS  PUB  38  and  DoD  STD  7935. 1-S  has  had  a  long  history.  As 
indicated  in  Kurihara  et  al  [3],  FIPS  PUB  38  was  derived  from  DoD  Manual  4120. 17M  [4]. 
The  foreword  of  DoD  STD  7935. 1-S  states  that  it  supersedes  the  same  manual.    The  basic 
format  and  content  guidelines  of  all  three  of  these  standards  are  nearly  identical. 
However,  the  DoD  manual  was  not  an  original  document,  being  based  on,  and  almost 
identical  with,  a  Navy  Department  instruction  which,  in  turn,  was  almost  a  direct  copy 
of  an  ADP  documentation  standard  issued  by  the  Naval  Command  Systems  Support  Activity 
(NAVCOSSACT  —  now  named  NARDAC)  in  1966.  [5]    This  original  standard  was  designed  to  be 
used  in  the  environment  in  which  NAVCOSSACT  developed  software.    In  this  environment, 
military  tours  of  duty  for  users  and  buyers  approximated  the  development  cycle  of 
software  (i.e.,  about  three  years).    In  many  cases,  the  originator  of  a  request  for  a 
software  project  would  be  rotated  in  his  military  duties  and  would  no  longer  be  with  a 
command  when  the  end-product  software  was  delivered.    Managers  at  all  levels  monitoring 
software  development  projects  faced  similar  rotations.    In  such  an  environment, 
stand-alone  documents  were  a  necessity. 

Today  the  concepts  of  this  original  standard  provide  guidelines  for  a  much  broader 
community,  one  which  encompasses  the  entire  federal  government.    For  the  majority  of  the 
members  of  this  community,  the  correlation  between  changing  buyers  and  users  and  the 
software  development  cycle  does  not  necessarily  exist.    Thus,  stand-alone  documents 
generally  are  not  required.    For  this  broader  community,  the  redundancy  specified  in 
FIPS  PUB  38  and  DoD  STD  7935. 1-S  unnecessarily  causes  problems  through  the  life  cycle  of 
a  software  project.    This  life  cycle  includes  the  period  of  maintenance  of  the  software 
as  well  as  its  development.    Typically,  the  maintenance  of  software  includes  the 
correction  of  latent  errors  discovered  in  the  operational  software  and  the  enhancement 
of  the  software  to  produce  new  or  modified  capabilities.    This  maintenance  activity  is 
hampered  by  the  redundancy  in  these  two  standards,  for,  as  we  subsequently  explain,  the 
redundancy  limits  the  visibility  and  traceability  of  the  software,  which  are  necessary 
ingredients  for  effective  software  maintenance. 

This  limitation  in  visibility  and  traceability  is  evident  from  consideration  of  two 
observations  made  in  preceding  paragraphs:    the  documents  produced  under  these  standards 
are  not  truly  stand-alone,  and  once  produced,  are  not  maintained.    The  only  reliable 
document  in  a  series  is  the  most  recent  one.    If  previous  documents  are  not  consulted, 
visibility  of  the  non-  redundant  part  of  those  predecessor  documents  is  lost,  which  may 
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have  considerable  impact  on  maintenance  activities.    On  the  other  hand,  consultation  of 
the  predecessor  documents  may  have  an  unfavorable  effect  on  software  maintenance,  since 
the  documents  are  of  questionable  reliability.    Traceability  through  the  sequence  of 
documents  is  impaired  or  destroyed. 

The  aforementioned  objections  could  be  overcome  by  maintaining  all  of  the  documents 
in  the  sequence,  so  that  each  one  is  always  up-to-date  and  thus  reliable.    But  such  an 
endeavor  greatly  increases  documentation  costs. 

A  strawman  document  termed  a  Comprehensive  Document  (CD)  has  been  suggested  as  a 
general  approach  to  revision  of  FIPS  PUB  38.  [3]    The  CD  would  be  a  data  base 
(maintained  current)  of  all  information  relevant  to  the  definition,  design,  coding, 
testing,  operation,  maintenance,  and  modification  of  the  system  being  documented.  In 
this  concept,  the  principal  software  documents  (e.g.,  an  FD  or  PS)  would  be  regarded  as 
extracts  from  the  CD  data  base.    The  CD  approach  has  many  noteworthy  benefits,  but  also 
has  a  potential  weakness  in  its  application:    the  publication  of  the  principal  documents 
as  extracts  from  the  CD  data  base  might  result  in  a  situation  identical  to  that  created 
by  the  FIPS  PUB  38  redundancy.    For  example,  the  FD,  SS,  and  PS  might  all  contain  the 
current  CD  paragraph  on,  say,  system  functions.    Since  they  are  published  over  a  period 
of  time,  and  since  change  is  endemic  to  software  projects,  each  document  might  contain  a 
different  definition  of  system  functions.    On  the  other  hand,  if  the  documents  extracted 
from  the  CD  data  base  were  not  redundant  (for  example,  system  functions  might  only  be 
extracted  for  the  FD),  then  the  problem  arises  as  to  how  to  promulgate  changes  to 
elements  of  the  CD  data  base.    One  solution  to  this  particular  problem  would  be  to 
maintain  and  republish  each  extracted  document  when  changes  occur;  another  would  be  to 
publish  the  CD  and  changes  to  the  CD  rather  than  publish  extracted  documents.  Further 
consideration  of  this  strawman  document  should  definitely  consider  this  potential 
problem  in  order  to  avoid  continuation  of  the  difficulties  caused  by  the  deliberate 
redundancy  specified  in  FIPS  PUB  38. 


4.    TELESCOPING  OF  TEST  DOCUMENTS 

Both  FIPS  PUB  38  and  DoD  STD  7935. 1-S  provide  guidelines  for  two  test  documents  — 
a  Test  Plan  written  during  the  design  and  programming  stages,  and  a  Test  Analysis  Report 
written  at  the  end  of  the  test  stage.    The  purpose  of  the  Test  Plan  is  "to  provide  a 
plan  for  the  testing  of  software;  detailed  specifications,  descriptions,  and  procedures 
for  all  tests;  and  test  data  reduction  and  evaluation  criteria"  (FIPS  PUB  38,  paragraph 
1.4.9).    The  purpose  of  the  Test  Analysis  Report  is  "to  document  the  test  analysis 
results  and  findings,  present  the  demonstrated  capabilities  and  deficiencies  for  review, 
and  provide  a  basis  for  preparing  a  statement  of  software  readiness  for  implementation" 
(FIPS  PUB  38,  paragraph  1.4.10).    The  Test  Plan  is  the  sole  test  document  preceding  the 
testing  of  the  software;  the  Test  Analysis  Report  is  the  sole  test  document  following 
the  testing. 

In  the  environment  at  NAVCOSSACT  referred  to  earlier,  where  the 
progenitor  of  FIPS  PUB  38  and  DoD  STD  7935. 1-S  was  created,  this  test 
documentation  schema  was  useful  and  satisfactory.    NAVCOSSACT  developed 
software  and  a  Test  Plan  concurrently.    When  development  of  the  software 
code  was  completed,  NAVCOSSACT  personnel  went  to  the  user  site,  conducted  a  test,  and 
submitted  a  Test  Analysis  Report.    The  user  and  the  buyer  (more  properly,  in  that 
environment,  the  sponsor)  had  no  involvement  with  development  nor  approval  of  the 
testing  process. 

In  the  broader  community  served  by  FIPS  PUB  38  and  DoD  STD  7935. 1-S,  users  and 
buyers  tend  to  be  more  involved  in  the  testing  process.    The  Test  Plan  generally  is 
submitted  to  the  buyer  and  user  well  before  testing  begins  and  is  approved  by  the  user 
and/or  buyer  before  any  testing  is  conducted.    If  the  Test  Plan  does  not  meet  the 
buyer's  approval,  it  must  be  revised  until  the  buyer  and  seller  can  mutually  agree  on 
Its  contents.    In  this  environment,  the  monolithic  Test  Plan  called  for  in  FIPS  PUB  38 
and  DoD  STD  7935-1. S  is  not  satisfactory. 
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The  problem  with  the  Test  Plan  is  that  it  is  too  comprehensive:    it  contains  not 
only  the  plans  for  testing  of  the  software  code,  but  also  the  detailed  procedures  for 
conducting  all  tests.    If,  when  the  Test  Plan  is  submitted  for  approval,  the  buyer 
objects  to  the  planned  testing  approach,  not  only  must  the  plan  portion  of  the  Test  Plan 
be  revised,  but  part  (or  possibly  all)  of  the  test  procedures  must  also  be  revised.  In 
essence,  it  is  generally  not  economically  justifiable  to  expend  resources  on  creating 
test  procedures  until  test  plans  have  been  approved. 

In  MIL-STD-1679  [6],  three  pre-test  documents  are  identified  and  separate  Data  Item 
Descriptions  are  defined  for  each  document:    (1)  DI-T-2142  for  test  plans,  (2)  DI-E-2143 
for  test  specifications,  and  (3)  DI-T-2144  for  test  procedures.    MIL-STD-1579  specifies 
that  all  test  plans,  specifications,  and  procedures  shall  be  subject  to  review  and 
approval  by  the  procuring  agency.    MIL-STD-1679  implies  a  sequence  in  producing  these 
three  documents.    The  sequence  is  made  more  explicit  in  the  Data  Item  Descriptions.  The 
development  of  three  separate  pre-test  documents  appears  to  be  more  cost  effective  than 
the  development  of  a  single  one  as  specified  in  FIPS  PUB  38  and  DoD  STD  7935. 1-S.  Yet 
the  cost  effectiveness  is  not  guaranteed:    in  a  recent  project,  the  authors'  company  was 
tasked  to  produce  Test  Plan  and  Test  Procedures  documents  in  accordance  with 
MIL-STD-1679,  with  both  documents  due  the  same  day}    By  destroying  the  sequential  nature 
of  these  documents,  the  procuring  agency  specified  a  requirement  identical  with  that  of 
DoD  STD  7935. 1-S.    In  the  project  cited,  through  negotiations  with  the  procuring  agency, 
the  delivery  dates  of  these  two  documents  were  shifted  so  as  to  make  them  sequential. 

When  the  use  of  FIPS  PUB  38  or  DoD  STD  7935. 1-S  is  prescribed  for  a  project,  the 
authors'  company  invariably  produces  a  Test  Plan  in  which  the  section  on  test 
descriptions  (Section  4  in  FIPS  PUB  38  and  Section  5  in  DoD  STD  7935. 1-S)  states  that 
detailed  test  procedures  will  be  separately  and  subsequently  produced.    These  procedures 
are  then  developed  following  approval  of  the  Test  Plan  by  the  procuring  agency.    In  this 
fashion,  wasted  effort  producing  unnecessary  or  undesired  test  procedures  is  avoided. 
This  is  a  practical  solution  to  the  problem  of  telescoped  testing  documents.    It  would 
be  preferable  to  modify  these  two  standards  to  provide  guidelines  for  a  Test  Plan  and  a 
separate  Test  Procedures  document. 


The  various  governmental  software  documentation  standards  vary  widely  in  the  degree 
of  flexibility  afforded  to  the  documentor  in  using  the  standards. 

At  one  extreme  are  MIL-STD-483  [7]  and  MIL-STD-1679  which  are  relatively  inflexible. 
MIL-STD-483  states  the  following  in  Appendix  VI  (Computer  Program  Configuration  Item 
Specification),  Section  60.4: 


All  paragraphs  in  this  appendix  preceded  by  the  designation  "Note:"  are  for 
guidance  only.    All  other  sections  of  the  appendix  are  requirements  for  the 
preparation  and  control  of  computer  program  specifications.    Contents  of  the 
specification  shall  be  arranged  in  accordance  with  the  format  and  paragraph 
headings  described  herein.    Deviations  from  the  requirements  of  this  appendix 
require  approval  of  the  procuring  activity. 


The  appendix  contains  four  notes,  all  indicating  that  additional  material  or 
references  can  be  included  in  a  specification.    The  appendix  also  contains  the  following 
four  paragraphs  specified  as  optional  for  inclusion  in  a  CPCI  Specification: 


5.    TAILORING  OF  SOFTWARE  DOCUMENTATION  REQUIREMENTS 


CPCI  Specification 
Paragraph  Number 


Title 


Part  I,  Section  6 
Part  II,  Paragraph  3.7.3 
Part  II,  Paragraph  3.11 
Part  II,  Section  6 


Notes 

Data  Base  Location  Requirements 
Program  Listings  Comments 
Notes 
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An  of  the  remaining  71  paragraphs  and  sections  for  a  CPCI  Part  I  and  Part  II 
Specification  are  required  by  MIL-STD-483, 

MIL-STD-1679,  in  Section  6,  specifies  that,  if  the  procuring  agency  desires  to 
order  data  that  it  has  had  created  through  work  tasking,  it  must  use  the  pertinent  Data 
Item  Descriptions  (DIDs)  from  a  list  of  17  of  them.    Each  of  these  DIDs  states  that  the 
document  it  pertains  to  shall  be  in  accordance  with  the  DID's  content  and  format 
instructions.    These  DIDs  do  not  contain  optional  paragraphs,  other  than  some 
appendices.    Only  the  DID  for  a  Software  Quality  Assurance  Plan  (DI-R-2174)  implies  that 
non-applicable  subjects  and  items  may  be  omitted.    The  only  flexibility  provided  under 
MIL-STD-1679  is  whether  a  document  should  or  should  not  be  included  in  a  Contract  Data 
Requirements  List. 

An  impact  of  this  lack  of  flexibility  might  be  a  reduction  in  the  number  of 
documents  produced  for  a  project.    In  a  survey  of  large  aerospace  firms  primarily 
developing  software  for  the  federal  government,  Lehman  [8]  reported  that  development  of 
over  nine  different  document  types  was  specified  on  the  average  for  projects  of  $20 
million  or  more,  while  development  of  only  six  different  document  types  was  required  on 
the  average  for  projects  of  less  than  $1  million.    (Document  types  in  this  survey 
included  both  source  code  listings  and  object  code  listings  and  tapes;  these  two* 
document  types  were  the  ones  most  frequently  required  for  projects.)    The  requirement 
that  a  project  use  an  inflexible  documentation  standard  might  be  a  possible  explanation 
of  these  results.    The  cost  of  creating  a  document  under  an  inflexible  standard  is  less 
than  linear  with  respect  to  project  size.    That  is,  the  creation  of  a  document  under 
such  a  standard  costs  only  slightly  less  for  a  small  project  than  for  a  large  one.  In 
this  circumstance,  the  number  of  documents  to  be  produced  on  a  small  project  might  be 
reduced  to  keep  documentation  costs  in  perspective. 

In  the  other  direction,  FIPS  PUB  38  and  DoD  STD  7935. 1-S  provide  considerable 
flexibility  to  the  documentor.    Paragraph  3.3.2  of  DoD  STD  7935. 1-S  allows  any  paragraph 
or  subparagraph  of  a  section  to  be  omitted  and  additional  paragraphs  to  be  freely 
added.    In  practice,  this  provision  allows  a  documentor  to  substitute  a  completely 
different  partition  in  any  given  section,  a  partition  for  which  no  standards  or 
guidelines  on  content  exist.    A  document  that  uses  only  the  section  titles  prescribed  in 
DoD  STD  7935. 1-S  is  in  conformance  with  that  standard.    Indeed,  the  authors  have  audited 
documents  which  met  standardization  requirements  in  just  such  a  fashion. 

FIPS  PUB  38  offers  essentially  the  same  or  greater  flexibility  as  does  DoD  STD 
7935. 1-S.    But  FIPS  PUB  38  is  a  set  of  guidelines,  not  a  standard.    A  software 
documentor  implicitly  has  the  option  of  not  following  a  set  of  guidelines.    The  section 
on  flexibility  in  FIPS  PUB  38  merely  makes  this  freedom  explicit.    However,  as  stated  in 
FIPS  PUB  38,  documentation  provides  information  to  support  the  effective  management  of 
ADP  resources  and  to  facilitate  the  interchange  of  information.    Adherence  to  the 
guidelines  enhances  the  likelihood  of  achieving  these  goals.    Offering  the  software 
documentor  the  license  to  completely  depart  from  the  guidelines  vitiates  the  program 
that  produced  the  guidelines. 

Documentation  standards  with  flexibility  intermediate  between  the  two  extremes 
represented  by  current  standards  would  be  very  beneficial.    The  standards  should  permit 
sufficient  tailoring  of  the  format  and  content  of  the  documents  to  cope  with  project 
size  and  complexity  without  vitiating  the  documents.    Then  the  production  of  all  the 
document  types  or  some  minimal  subset  of  them  could  be  required  for  all  projects,  with 
each  document  type  tailored  as  appropriate  for  the  project  being  documented. 


6.  CONCLUSIONS 

The  software  documentation  standards  considered  in  this  paper  were  MIL-STD-483, 

MIL-STD-1679,  DoD  STD  7935. 1-S,  and  FIPS  PUB  38.  Based  on  our  experience  with  this 
sample,  we  offer  the  following  conclusions: 

1.       A  tradeoff  exists  between  making  each  document  in  a  documentation  chain 
stand-alone  on  the  one  hand,  and  maintaining  visibility  and  traceability 
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using  this  chain  on  the  other  hand.    If  each  document  is  to  be 
self-contained,  visibility  and  traceability  are  generally  cost-prohibitive  to 
maintain  throughout  a  project's  life  cycle.    If,  on  the  other  hand,  no 
overlap  among  documents  exists,  then  traceability  is  difficult  to  establish 
(i.e.,  the  links  in  the  chain  do  not  interlock  and  are  tangent  to  one  another 
at  best). 

2.  Again,  for  purposes  of  maintaining  traceability,  a  document  once  produced 
should  be  maintained  (i.e.,  kept  up-to-date).    In  the  standards  in  our 
sample,  this  document  maintainance  aspect  is  not  emphasized  (and  is,  at  best, 
implicit) . 

3.  Some  of  the  standards  do  not  take  cognizance  of  the  reality  that  before 
software  is  tested,  a  test  plan  should  first  be  formulated  specifying  a 
testing  approach,  and  then  step-by-step  procedures  detailing  this  approach 
should  be  formulated.    FIPS  PUB  38  and  DoD  STD  7935. 1-S  call  for  a  single 
pre-test  document  that  combines  planning  and  procedure  writing  into  a 
concurrent  exercise.    Since  test  procedure  development  is  generally  an 
extremely  labor  intensive  activity,  performing  test  planning  and  procedure 
writing  concurrently  can  be  an  extremely  profligate  activity  if  the  testing 
approach  in  the  plan  does  not  meet  buyer/user  approval. 

4.  Up  to  a  point,  a  standard  for  a  document  should  be  viewed  as  a  checklist  of 
items  to  be  addressed  in  the  document.    Some  discretion,  however,  should  be 
used  in  applying  the  checklist.    Blind  adherence  to  the  checklist  can  lead  to 
a  document  that  obfuscates  rather  than  clarifies.    In  the  other  extreme, 
keeping  section  headings  but  ignoring  the  basic  intent  of  the  items  in  the 
checklist  makes  a  mockery  of  the  standard.    A  documentation  standard  should 
be  viewed  as  something  that  ignites  the  process  of  writing  a  document.  It 
jogs  the  mind  into  action,  stimulates  the  creative  processes,  and  bounds  them 
with  guidelines  that  should  be  followed  as  reason  and  project  circumstances 
dictate. 
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NBS  FIPS  Software  Documentation  Workshop 
March  3,  1982 


Case  Studies,  Management  Guidance 
and  Quality  Criteria 
for 

Software  Docmumentation 
by 

James  N.  Or ton 
Software  Documentaton  Manager, 
ALQ-131  and  TWS  Projects 


During  the  past  decade  increasing  demands  have  been  put  in  acceler- 
ating fashion  upon  the  software  documentation  function  in  the  form  of  (1) 
the  increasing  complexity  and  scope  of  radar  systems  software 
applications,  (2)  the  increasing  information  requirements  of  an  increasing 
variety  of  Government  software  documentation  standards  and  specifications, 
and  (3)  increasing  Government  attention  to  enforcing  contractor 
fullfillment  of  these  requirements. 

Westinghouse  is  attempting  to  meet  these  demands  by  developing 

(1)  Standardized  yet  non-stultifying  approaches  to  software 
documentation  in  acceptance  of  today*  s  reality  of 
dynamically  proliferating  and  changing  Government  software 
standards  and  specifications; 

(2)  Automatic  docimientation  tools  utilizing  word  processor  and 
computer  systems  operating  initially  apart  but  eventually 
in  concert; 

(3)  A  data  base,  built  up  from  accumulating  software 
documentation  experience,  designed  both  to  develop  overall 
documentation  quality  criteria  and  to  minimize  the 
documentation  startup  effort  for  future  projects 
anticipated  to  relate  in  varying  degrees  to  present 
project  s; 

(4)  Management  techniques  for  putting  this  documentation 
process  into  effect  using  the  most  cost-efficient  yet 
ego-sustaining  division  of  labor  between  the  software 
designer  and  programmer  on  the  one  hand,  and  the 
"information  specialist"  or  document  format  designer  on  the 
other. 

These  ideas  will  be  explained  and  evaluated  in  the  harsh  light  of 
experience  over  the  past  year  on  two  Westinghouse  radar  systems  Software 
documentation  projects. 
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steps  Toward  a  Solution 


•  standardization 

•  Automation 

•  Data-Based  Experience 

•  "Creator/Documentor  Interface"  Management 


Standardization 


•  Interpretation  of  Standards  and  Specifications 

-  MIL-STD-483  (1970  &  1979) 

-  MIL-STD-490 

-  MIL-STD-1679 

-  DID's 

•  Document  Format  Specifications 
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Automation 

•  Flowchart 

•  Data  Description 

-  Internal 

-  External 

•  Set/Use  Matrix  (Inter-CPC  or  Inter-Subprogram) 

•  Data  Itenn  Cross  Reference 

-  Internal 

-  External  (I/O) 

•  Document  File  Management  (WP) 


Data-Based  Experience 


•  Document  Format  Specification  Files 

•  Document  Files 
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"Creator/Documentor  Interface"  Management 

•  The  Creator  (S/W  Designer,  Programmer)  is 

-  Responsible  for  Content 

-  Indispensable  to  Documentation  Effort  Success 

•  The  Documentor  ("Information  Specialist")  is 

-  Responsible  for  Standards/Specs  Interpretation 

-  Responsible  for  Format/Information  Presentation 

■  Part  of  a  Service  Organization 

•  To  S/W  Engineering 

•  To  Project  Management 

•  Both  Should  Work  Together,  With  Complete  Mutual  Under- 
standing, From  Day  One 


The  Real  World 


•  TWS  Project 

•  ALQ-131  Project 

•  ASPJ/CPMS  Project 
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TWS  Project  (AF  Single-CPU  ECM  System) 

•  Documents:  CCR  CI,  CPM,  CSR,  DPFS,  DS,  MM,  PS,  SDD, 

TER,  CSTP,  UM,  VDD 

•  Standards/Specs:  Mi!=Std»483  (1970),  Mi!'Std-490,  DlD's 

•  Techniques: 

-  Document  Format  Specs 

-  Automation  of  Flowcharts  (Annotation  Language/Autoflow 
Adaptation) 

-  Word  Processor  File  Library  Initiation  (DSF's,  Docu- 

Documentation 


ALQ-131  Project  (AF  Double-CPU 
ECM  System) 

•  Documents:  CCR  CPS,  CPDP,  DS(3),  IS,  PS(3),  SR,  TR,  UM, 

VDD(3) 

®  Standards/Specs:  MihStd-483  (1979),  Mii=Std"490,  DlD's 

•  Techniques: 

-  Document  Format  Specs 

-  Automation  of  Flowcharts,  Data  Descriptions  (Internal), 
Set/Use  Matrix,  Data  Item  Cross  Reference  (Internal  and 
External) 

-  Word  Processor  Library  Expansion  (DFS's,  Documents) 

-  Management  (Centralized) 
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ASPJ/CPMS  Project  (Two  Navy  Multiple-CPU 

ECM  Systems) 

Documents:  IDS(2),  PPS(2),  PDS(2),  PDD(2),  DBDD(2),  PPD(2), 
CPTR  CPTS(2),  CPTPr(2),  CPTR(2),  CM,  VDD(2), 
CPIN  Req  (2),  SDP 

•  Standards/Specs:  Mil-Std-1679,  Mil-Std-490,  DID's 

•  Techniques: 

-  Document  Format  Specs 

-  Automation  of  Data  Descriptions  (Internal),  Set/Use 
Matrix,  Data  Item  Cross  Reference  (Internal  and 
External) 

-  Word  Processor  Library  Expansion  (DFS's,  Documents) 

-  Management  (Centralized) 


Conclusion 


•  [Sometimes,]  "I'd  rather  be  in  Philadelphia." 

-  W.C.  Fields 

•  [Nonetheless,]  "Well  begun  is  half  done." 

-  Poor  Richard's  Almanac 
(or  equivalent) 
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Experiences  in  Software  Standard  Selection 
And  Application  -  A  Case  History 

Thomas  L.  Hannan  and  Alice  A,  Wong 

Federal  Aviation  Administration 
Washington,  DC 

This  paper  presents  the  findings  of  analyses  conducted  by 
the  Systems  Research  and  Development  Service  of  the  Federal 
Aviation  Administration  regarding  the  applicability  of  exist- 
ing software  standards  to  the  development  and  implementation 
of  the  Air  Traffic  Control  Advanced  Computer  System.     A  brief 
description  of  system  requirements,  acquisition  methods,  and 
standardization  objectives  is  presented  with  a  description 
of  the  standard  review  activities  and  resultant  findings. 
Preliminary  conclusions  based  on  these  findings  are  described, 
and  the  issues  pending  resolution  are  identified. 

Keywords:     Software  standards;  Selection  criteria;  Advanced  Computer  System 

1.     ADVANCED  COMPUTER  SYSTEM 

The  Air  Traffic  Control  (ATC)  System  is  a  complex  system  incorporating  navigation, 
communication,   surveillance,  and  automation  facilities,  equipments,  and  personnel.  The 
Advanced  Computer  System  (ACS)  will  be  the  major  automation  component  of  the  ATC  system 
and  will  provide  the  ATC  specialist  the  data  and  information  required  for  planning  and 
control  actions.     In  addition  to  being  complex,   the  ACS  is  critical.     As  the  ACS  is 
comprised  mainly  of  software,   it  is  the  concern  about  this  software  that  drives  the 
search  for  means  to  insure  its  integrity  and  improve  its  maintainability  over  the  system's 
life  cycle. 

1.1  Requirements 

ACS  software  requirements  encompass  functional,  performance,  and  interface  aspects  of  the 
system.     The  software  must  perform  radar  data  processing,  weather  data  processing,  air- 
craft tracking,  flight  plan  data  processing,  graphic  and  tabular  presentation,  and  system- 
sustaining  operations.     It  must  interface  with  a  variety  of  both  long-range  and  short- 
range  aircraft  and  weather  surveillance  equipment ,  a  variety  of  associated  control  facil- 
ities and  user  equipment,  and  a  large  number  of  ATC  operations  and  supervisory  personnel. 
The  software  must  be  reliable,  maintainable,  and  adaptable  to  a  wide  variety  of  geographic 
configurations,  air  traffic  density  and  service  profiles,  and  evolutionary  procedural  con- 
cepts. 

1.2  Acquisition 

The  ACS,   including  its  software,  will  be  procured  on  a  competitive  basis  involving 
multiple-year,  multiple-contractor  solicitations  spanning  a  relatively  long  time  frame. 
Each    of  these  aspects  adds  a  dimension  of  complexity  to  the  acquisition.  Requirements 
must  be  uniformly  communicated,  provide  a  common  evaluation  basis,  and  facilitate  discrim- 
ination among  offerings.     System  engineering,  verification  and  validation,  development  and 
integration  activities  must  be  carefully  coordinated.     System  products  must  be  assimilated 
into  a  common  operational  inventory,  technology  evolution  must  be  accommodated,  and  pro- 
gram continuity  must  be  maintained. 
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1.3    Standardization  Objectives 

Having  defined  the  requirements  and  identified  the  constraints,  it  remained  to  formalize 
the  plan  and  institute  the  procedures  needed  to  provide  assurance  that  it  will  be  carried 
out.     Procedures  were  sought  that  would: 

•  Assure  Adequacy  of  the  software  with  respect  to  the  specified  requirements, 

•  Contain  Risk  of  the  software  development  efforts  within  acceptable  limits. 

•  Promote  Economy  of  both  the  development  and  operation  of  the  software. 

•  Assure  Interoperability  of  the  software  with  other  system  components. 

•  Promote  Adaptability  of  the  software  to  environmental  differences  and  evolutionary 
change. 

Selection  and  application  of  existing  software  standards  were  to  be  accomplished  in  light 
of  their  individual  contributions  to  these  objectives. 

2.     STANDARDS  REVIEW  ACTIVITIES 

2.1  Approach 

To  formulate  the  needed  set  of  software  standards,  a  sequence  of  studies  was  conducted. 
First,  the  areas  in  which  software  standards  application  was  documented  were  surveyed. 
Second,  available  standards  within  these  areas  were  identified  and  collected.  Third, 
standards  were  evaluated  with  respect  to  the  specified  objectives;  the  most  appropriate 
standards  were  to  be  selected;  and  tailorings  were  to  be  devised  to  integrate  them  into  a 
consistent  package. 

2.2  Application  Areas 

Within  three  major  areas  (Project  Management,  Software  Development,  and  Test  and 
Reliability),   several  categories  of  standards,  were  identified.     Table  1  indicates  the 
areas,  their  respective  categories,  and  the  objectives  addressed  by  each  category  of 
standard. 

3.  FINDINGS 

Existing  standards  do  not  comprise  a  complete,  consistent  set  of  procedures  which  satisfy 
the  needs  of  the  ACS  effort.     Three  attributes  of  the  standard  set  identified  as  being 
most  appropriate  are  worthy  of  note:     (1)  Varying  Objectives — attributable  to  originating 
source;   (2)  Varying  Level  of  Specificity — attributable  to  a  lack  of  elementary  principles, 
and  (3)  Unaddressed  Major  Areas — attributable  to  the  lack  of  concurrence  among  current 
practitioners . 

3.1  Varying  Objectives 

The  National  Bureau  of  Standards,   the  American  National  Standards  Institute,  and  the 
Department  of  Defense  constitute  the  primary  sources  of  standards  identified.     Each  source 
addresses  a  different  audience  from  a  different  perspective  with  a  different  terminology. 
The  result  of  attempting  to  combine  them  is  to  incur  a  significant  "normalization"  effort. 

3.2  Varying  Levels  of  Specificity 

Four  types  of  standard  documents  are  identifiable;  definitions,  exposition,  recommenda- 
tions, and  requirements.     Firm  definitions  or  expositions  of  elementary  principles  are 
noteworthy  by  their  absence.     Recommendations  and  requirements  exhibit  a  tendency  to 
cluster  in  the  more  "mechanical"  categories,  and  vary  widely  in  level  of  detail.  Require- 
ments appear  to  be  based  less  on  demonstrated  efficacy  than  on  personal  preference. 
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STANDARD  OBJECTIVE 


Adequacy 

Risk  Economy 

Int  er operab  il ity 

Adaptability 

rKUJtLi  MAJNIALrJirlrLlNi 

Life  Cycle  Definition 

X 

X  X 

Configuration  Control 

X 

X 

X 

Document at ion 

X 

X 

X 

Human  Factors 

X 

X 

X 

Simulation 

X 

X 

Miscellaneous 

X 

X 

SOFTWARE  DEVELOPMENT 


Languages 
Programming 
Data  Bases 

Computer  Communication 
Med  ia 

Hardware/Software  Interface 
TEST  AND  RELIABILITY 

Quality  Assurance 
Reliability /Maintainability 
Test/Test  Documentation 
Terminology 


TABLE  1:     Objectives  of  Software  Standards 


3-3    Unaddressed  Major  Areas 

Adequate  standards  for  representing  software  requirements,   software  designs,  and  actual 
code  were  not  identified.     No  guide  to  the  applicability  of  a  given  representation  to  a 
given  application  was  identified,  and  no  standard  for  a  given  representation  appeared  to 
have  universal  agreement.     Reliability  and  maintainability  standards  were  not  identified 
although  candidate  techniques  exist. 

4.  CONCLUSIONS 

A  complete,   consistent  set  of  standards  is  needed,  but  is  currently  not  available.  To 
use  an  incomplete  set  would  be  to  risk  the  value  of  those  that  were  used,  and  to  use  an 
inconsistent  set  would  be  to  incur  unnecessary  costs  at  best.     At  first  glance,   it  would 
appear  that  a  monumental  effort  would  be  required  to  resolve  the  problem. 

Upon  further  thought,  however,   it  becomes  clear  that  creation  of  a  total  set  of  standards 
covering  everything  from  general  life  cycle  definition  to  detailed  coding  standards  is 
not  what  is  needed.     Careful  examination  reveals  two  distinct  classes  of  standards;  stand- 
ards with  a  "capital  S",  and  standards  with  a  "small  s". 

•      "Standards."     These  define  mandatory  requirements  based  on  universally  accepted 
principles.     They  should  be  limited  to  the  specification  of  "what"  should  be  done 
rather  than  "how"  it  should  be  done.     They  should  address  product  attributes  of  form, 
fit,  or  function.     They  should  be  durable.     They  are  in  the  domain  of  the  purchaser. 
Currently,   they  are  "meta-standards"  that  require  compliance  with  a  specific  "stand- 
ard"  (small  s)  to  be  negotiated. 
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XX  X 


X 

X 

X 

X 

X 

X 

X 

X 

X 

X  XX 


X  X 


X 

X 

X 

X 

X 

•      "standards."     These  define  specific  alternate  instances  which  satisfy  the  require- 
ments of  "Standards"   (capital  S).     They  should  specify  in  detail  "how"  a  require- 
ment is  to  be  met.     They  should  address  process  methods  and  procedures.     They  should 
reflect  the  most  appropriate  technology.     They  are  in  the  domain  of  the  seller. 
Currently,  they  are  recommended  practices  generally  integral  to  a  development 
organization's  preferred  way  of  doing  business. 

This  view  is  consistent  with  generally  accepted  specification  practices  and  also  appears 
in  keeping  with  the  intent  of  the  Federal  Information  Processing  Standards  produced  to 
date. 

From  the  purchaser's  perspective,  then,  what  is  needed  is  a  complete  and  consistent  set 
of  "Standards"  that  cover  the  generic  needs  of  system  development  aspects  such  as 
quality  assurance,  documentation,  and  training.     It  would  seem  to  be  the  function  of  the 
competitive  marketplace  to  produce  successively  better  "standards"  that  satisfy  these 
needs . 

In  the  preparation  of  each  type  of  standard,  care  should  be  taken  not  to  infringe  on 
the  realm  of  the  other  type.     "Standards"  should  not  dictate  specific  techniques  at  the 
expense  of  innovation.     Similarly,  "standards"  should  not  be  promoted  as  requirements 
for  the  same  reason.     There  is  a  place  for  a  "Standard"  for  design  documentation  and 
there  is  a  place  for  a  "standard"  for  program  design  language;  they  should  be  kept  in 
their  respective  places. 

Finally,   in  the  preparation  of  standards,  especially  "Standards",  efforts  should  be 
expended  in  alleviating  the  deficiencies  already  noted.     Parochial  sources  of  standards 
should  agree  on  common  objectives;  they  should  at  least  agree  on  a  common  terminology. 
Standards  should  be  based  on  principles;  empirical  if  not  elementary.     Standards  should 
have  the  concurrence  of  those  affected;  buyers  and  sellers  alike.     We  cannot,  each  of 
us,   continue  to  pursue  our  own  individual  paths  and  hope  to  successfully  meet  the 
challenges  of  the  future. 
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SESSION  A:    Applying  Documentation  Standards 

Summary  of 
Findings  and  Recommendations 

R.  J.  Gavin 
Federal  Deposit  Insurance  Corporation 

The  papers  presented  during  this  session  highlighted  various  problems  encountered  by  soft- 
ware groups  both  inside  and  outside  the  Federal  government  as  they  have  attempted  to  cope 
with  the  array  of  existing  software  documentation  standards. 

Documentation  preparation  should  be  treated  as  a  continuing  effort,  evolving  from  the 
preliminary  draft  through  changes  and  reviews  to  software  delivery,  with  subsequent  updates 
indicated  by  user  feedback.    If  the  documentation  develops  as  the  code  develops,  by  the 
time  the  code  is  completed    the  documentation  will  be  current. 

A.  Existing  Standards 

Existing  guidelines  provide  some  good  "how-to"  approaches  to  the  preparation  of  basic 
software  documentation.    The  participants  in  this  session  indicated  areas  in  which 
these  approaches  could  be  improved: 

1.  Many  expressed  a  general  lack  of  awareness  as  to  what  software  guidelines  are 
currently  available.    Therefore,  a  significant  segment  of  the  users  are  reinventing 
the  wheel  instead  of  utilizing  software  guidelines  which  are  already  in  existence. 

2.  FIRS  PUB  38  guidelines  discuss  ten  basic  documents.    There  is,  however,  significant 
redundancy  between  the  various  documents  in  a  set.    This  redundancy  could  be 
reduced  while  still  retaining  the  necessary  informational  content  for  project 
auditing,  analysis,  or  update. 

3.  The  current  software  guidelines  do  not  adequately  address  system  security  or 
interactive  applications.    The  emphasis  is  on  batch  systems  with  discrete  input 
and  output. 

4.  Participants  in  this  session  expressed  the  desire  for  some  guidance  regarding  the 
relevance  and  appropriateness  of  the  different  documents  to  widely  divergent  types 
of  applications  software. 

B.  New  Standards 

A  consensus  developed  that  new  guidelines  should  be  created  to  address  the  areas  of: 

1.  All  phases  of  software  system  life  cycles. 

2.  System  maintainability,  reliability,  security,  and  testing. 

C.  Analysis  and  Research 

Speakers  and  attendees  discussed  several  areas  for  additional  research  and  development; 

1.  The  implementation  of  documentation  for  the  automated  office. 

2.  The  rapid  advance  of  user-developed-and-implemented  software. 

3.  Guidelines  for  testing  and  verification  of  software  documentation. 

4.  Use  of  new  technology  and  automated  support  tools  for  documentation  preparation  and 
maintenance. 


40 


Conclusions 

The  users  represented  in  this  session  have  applied  existing  FIPS  software  documentation 

guidelines  with  mixed  results  over  uniformly  long  periods  of  time.    They  expressed  keen 

interest  in  the  next  steps  in  the  development  of  software  documentation  standards  and 

are  much  aware  of  the  dangers  inherent  in  the  spread  of  undocumented  software. 
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Session  B:    Documenting  for  Operation  and  Maintenance 
Introduction 
Charles  L.  Gerhardt 
UoSo  Department  of  Agriculture 


The  National  Bureau  of  Standards  describes  the  software  life  cycle  as  consisting  of  three 
general  phases.    During  the  Initiation  phase,  the  objective  and  general  definition  of  the 
requirements  for  the  software  are  established.    During  the  Development  phase,  the  software 
is  maintained,  evaluated  and  changed  as  additional  requirements  are  identified.  These 
phases  and  their  definitions  are  arbitrary  but  they  are  adequate  for  discussing  the  process 
of  software  development. 

FIPS  Publications  64  and  38  present  in  detail,  documentation  content  guidelines  for  the 
Initiation  and  Development  phases  respectively.    There  are  no  documentation  content  guide- 
lines for  the  Operation  phase.    Is  there  a  need  for  documentation  guidance  for  this  phase? 
The  General  Accounting  Office  report  entitled  Federal  Agencies'  Maintenance  of  Computer 
Programs:    Expensive  and  Undermanaged  (ASMD-81-25,  February  26,  1981)  presents  the  results 
of  a  survey  of  over  400  governmental  data  processing  installations.    This  survey  indicated 
over  50%  of  software  maintenance  results  from  modifications  or  enhancements  required  to  make 
the  software  perform  more  in  the  user  function.    Federal  agencies  spend  millions  of  dollars 
annually  on  computer  software  maintenance  and  it  is  during  the  Operation  phase  that  sound 
management,  including  documentation  of  software  modifications  and  enhancements,  must 
continue. 

The  papers  presented  in  this  session  describe  how  FIPS  documentation  guidelines  have  been 
adapted  in  a  governmental  agency;  present  an  approach  used  to  document  modifications  of  a 
commercial  software  product;  point  out  the  unique  documentation  requirements  of  on-line, 
real-time  systems;  and  propose  specific  documentation  content  guidelines  for  the  Operation 
phase  of  the  software  life  cycle. 
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The  Development  and  Implementation 
of  Uniform  ADP  Documentation 
Standards  at  FAA 

Harvey  P.  Kaplan 

Department  of  Transportation 
Federal  Aviation  Administration 
Office  of  Management  Systems 


This  paper  chronicles  the  ex- 
periences of  the  Federal  Aviation 
Administration  (FAA)  in  tailoring 
uniform  documentation  standards  to 
the  guidelines  contained  in  FIPS 
PUB  38.  The  end  product  which 
emerged  from  this  effort  was  an 
agency  directive  which  defines  re- 
quirements for  technical  documents 
produced  during  the  development  of 
all  approved  automated  data  sys- 
tems. The  directive  consists  of 
twenty  three  specific  document  con- 
tent standards  defined  as  documen- 
tation elements.  These  documenta- 
tion elements  are  further  arranged 
into  documentation  categories 
which  are  guidelines  for  packaging 
the  elements.  This  paper  also  de- 
scribes the  approach  employed  in 
developing  the  standards,  signifi- 
cant benefits  accruing  from  the 
use  of  the  standards,  and  con- 
cludes with  a  summary  of  conclu- 
sions and  additional  needs  which 
were  a  direct  result  of  uniform 
documentation  standards. 

Keywords:  Documentation  categor- 
ies; Documentation  elements;  Uni- 
form documentation  standards;  User 
guide  documentation  standards; 
User  involvement. 

I.  INTRODUCTION 

The  Federal  Aviation  Administration 
(FAA)  has  long  recognized  the  vital  impor- 
tance of  sound  documentation  practices  in 
the  operation  of  it's  data  processing  facili- 
ties. The  issuance  of  FIPS  PUB  38  in  1976 
coupled  with  major  decisions  regarding 
agency  software  and  hardware  systems  height- 
ened the  requirement  for  uniform  documentation 
standards.    The  FAA  has  been  a  long  standing 


advocate  of  FIPS  PUBs  in  conjunction  with 
its  own  ADP  Standards  Program.  However,  an- 
alysis of  FIPS  PUB  38  quickly  revealed  that 
a  further  translation  was  required  in  order 
to  introduce  a  meaningful  document  to  the 
FAA  ADP  community.  Accordingly,  the  thrust 
of  this  effort  centered  on  tailoring  FIPS 
PUB  38  to  the  practical  needs  of  FAA,  while 
still  retaining  its  structure  and  intent. 

The  purpose  of  this  paper  is  to  de- 
scribe FAA's  experiences  in  developing  uni- 
form documentation  standards;  highlighting 
major  benefits  of  documentation  standards; 
and  concluding  with  findings,  advantages, 
and  recommendations. 

II.  SUMMARY  RECOMMENDATIONS 

A  comprehensive  set  of  documentation 
standards  is  essential  to  the  management  of 
any  ADP  system.  System  documentation  provid- 
es the  chief  means  by  which  personnel  re- 
sponsible for  the  design,  implementation, 
use,  and  operation  of  a  system  communicate 
with  each  other. 

The  benefits  which  accrue  to  a  large, 
geographically  dispersed  organization  such 
as  the  FAA  are  significant  in  terms  of 
efficient  use  of  hardware,  software,  and 
personnel  resources.  Documentation  standards 
enable  document  orginators  to  prepare  their 
material  according  to  a  preset  logical  for- 
mat. The  documents  produced  will  be  familiar 
to  others  in  the  organization  and  designed 
to  meet  common  needs. 

The  quality  of  system  software  and 
applications  programs  is  also  enhanced  by 
standardized  documentation.  Applications 
which  are  operated  at  multiple  facilities 
become  more  transferable  from  one  facility 
to  another.  Duplication  of  effort  among  fa- 
cilities is  thereby  minimized  since  standard 
documentation  promotes  a  general  awareness 
of  the  applications  available  throughout  the 
organization. 

Finally,  good  ADP  documentation  prac- 
tices facilitate  personnel  training  since 
both  the  standards  and  resultant  documents 
provide  an  excellent  source  of  training 
material.  The  resulting  shorter  learning 
times  tend  to  minimize  the  impact  of  trans- 
fers or  other  ADP  personnel  turnovers. 

III.  TECHNICAL  DISCUSSION 

The  success  of  the  overall  effort 
hinged  on  gaining  acceptance  and  receiving 
cooperation    from    key    personnel  dispersed 
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throughout  FAA's  14  ADP  facilities.  In 
order  to  achieve  this  goal  every  effort 
was  made  to  seek  involvement  and  participa- 
tion from  personnel  who  would  ultimately 
be  the  users  of  the  documentation  standards 
or  be  responsible  for  their  completion. 
Both  formal  as  well  as  informal  lines  of 
communication  were  established  throughout 
the  duration  of  the  project. 

Since  most  facilities  had  some  form 
of  existing  documentation,  one  of  the  first 
tasks  was  to  complete  an  in-depth  review 
of  the  current  standards  and  adopt  those 
that  were  appropriate  for  consideration. 
One  of  the  significant  challenges  during 
this  phase  of  the  project  was  to  develop 
standards  which  strike  the  proper  balance 
between  flexibility  and  uniformity.  The 
standards  also  had  to  reflect  a  sensitivity 
to  the  requirements  of  FAA's  regional  of- 
fices so  their  responsibilities  would  not 
be  subordinated  to  unnecessarily  rigid  con- 
trol s . 

It  has  been  FAA's  experience  that  stan- 
dards are  not  self-implementing,  but  re- 
quire a  participative  role  on  the  part  of 
the  users.  Therefore,  no  effort  was  spared 
to  maximize  the  communication  between  all 
parties  involved  in  the  effort.  Formal 
coordination  was  utilized  at  appropriate 
stages  of  project  development.  Where  signi- 
ficant conflicts  arose,  compromises  were 
reached  to  the  satisfaction  of  affected 
offices.  At  all  times  an  atmosphere  of 
open  and  candid  communications  was  main- 
tained. 

The  product  which  emerged  embodied  the 
concepts  established  during  the  project 
approach  phase.  Thus,  the  nature  and  extent 
of  documentation  required  during  each  phase 
of  system  development  vary,  depending  on 
the  scope,  complexity,  and  type  of  system 
being  documented.  Four  levels  of  documenta- 
tion were  established  to  accommodate  these 
varying  requirements.  This  concept  permits 
flexibility  in  documentation  requirements, 
thus  eliminating  burdensome  documentation 
for  simple,  less  complex  systems. 

Document  content  standards  defined  as 
documentation  elements  provide  specific  re- 
quirements concerning  the  documentation  of 
an  automated  data  system.  The  FAA  stan- 
dards prescribe  up  to  twenty  three  of  the 
following  documentation  elements: 

1.  Documentation  Check  List 

2.  System  Description 

3.  Program  Description 

4.  Functional  Flowchart 
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5. 

Prnrp«;s  Flnwrhart 

6. 

Proaram  Flowchart 

7. 

File/Data  Base  Decription 

8. 

Input  Document  Definition 

9. 

End  Product  Definition 

10. 

Data  Element  Description 

11 . 

Data  Grid 

12. 

Center /Rea i nn  Tntprfarp 

13. 

Job  Control 

14. 

System  Run  Information 

15. 

Data  Collection  and  Preparation 

16. 

Peripheral  Process  Guide 

17. 

Distribution  fiuidp 

18. 

User  Job  Initiation  Prnrpdiirp*; 

19. 

Output  Review  and  Resubmission 

20. 

Remote  Processing 

21 . 

System  Test  Procedure 

22. 

Evaluation  of  System  Test  Results 

23. 

Glossary  of  Terms 

The 

documentation  elements  are  further 

arranged 

into   the   following  documentation 

categories: 

1 . 

System  Design  Specification 

2. 

System  Documentation 

3. 

Program  Documentation 

4. 

Computer  Operating  Documentation 

5. 

User's  Guide 

6. 

System  Test  Plan 

7. 

Data  Element  Documentation 

8. 

Distribution  Guide 

Concurrent  with  distribution  of  the 
approved  directive,  a  videotape  training 
presentation  was  prepared  which  enhanced 
understanding  of  the  documentation  stan- 
dards. 


IV.  CONCLUSIONS 

The  FAA  has  reaped  numerous  benefits 
from  utilization  of  uniform  documentation 
standards.  Most  prominent  of  these  include 
an  increased  awareness  of  software  sharing, 
eliminating  duplication  of  effort,  minimiz- 
ing work  disruption  created  by  personnel 
turnover,  providing  an  excellent  source  of 
training  material,  and  contributing  to  the 
overall  efficiency  of  it's  data  processing 
facilities.  In  addition,  several  favorable 
by-products  emerged. 

Faced  with  austere  staff  levels,  the 
FAA  has  placed  increasing  reliance  on  con- 
tractual support.  The  documentation  stan- 
dard directive  has  proved  to  be  a  useful 
measure  in  determining  contractually  produc- 
ed documentation.  FAA  contracting  officers 
normally  require  that  the  directive  be 
cited  in  the  statement  of  work  for  software 
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development  efforts.  Thus,  it  has  provided 
an  excellent  source  of  documentation  re- 
quirements for  both  contractor  and  FAA,  at 
the  negotiation  stage,  thereby  eliminating 
any  ensuing  misunderstandings.  The  reaction 
from  contractors  has  been  overwhelmingly 
positive.  Several  have  even  suggested  they 
intend  to  adopt  FAA  documentation  require- 
ments for  their  own  internally  developed 
systems. 

A  post  evaluation  of  the  uniform  docu- 
mentation standards  led  to  the  development 
of  user  guide  documentation  standards. 
Though  addressed  in  the  former  document, 
increased  emphasis  on  distributed  data  pro- 
cessing systems  and  growing  reliance  on 
user  interaction  dictated  the  need  for  a 
separate  directive.  The  user  guide  stan- 
dard represents  a  logical  extension  of  the 
earlier  effort.  The  documentation  contained 
in  this  directive  is  geared  to  support 
non-ADP  personnel  who  interact  with  ADP 
systems. 

In  retrospect,  if  there  is  a  single 
dominant  quality  which  characterized  the 
success  of  producing  uniform  documentation 
standards,  it  was  strong  communications. 
By  their  very  nature,  standards  are  not 
appealing  to  the  recipient.  However,  when 
it  is  demonstrated  that  an  honest  and  sin- 
cere effort  is  being  made  to  incorporate 
each  organization's  thoughts  in  developing 
standards  which  can  make  their  job  more 
efficient  and  orderly,  a  productive  re- 
lationship is  established.  This  rapport  can 
be  a  source  of  meaningful  achievements  and 
should  be  regarded  as  a  valuable  asset. 


45 


NBS  FIPS  SOFTWARE  DOCUMENTATION  WORKSHOP,  MARCH  3,  1982 


SUPPLEMENTAL  DOCUMENTATION 
OF  MODIFICATIONS  TO  SOFTWARE  PRODUCTS 
ON  SMALL  TO  MEDIUM  SIZED  SYSTEMS 

BY  HENRY  A.  LEWIS 

DCD  COMPANY/DIVISION  OF  BORG  ENTERPRISES 

Supplemental  Documentation  of  Modifications  to  Software  Products  on  Small  to  Medium 
Sized  Systems  is  designed  to  provide  a  simple  structure  for  analyzing  proposed  modifica- 
tions, documenting  development,  and  archiving  pertinent  project  documents.  This  method 
is  supplemental  to  existing  documentation  procedures.  The  system  approach  is  to  keep  the 
method  basic  and  straightforward  while  highlighting  such  historicaly  troublesome  areas  as 
development  plans,  future  referencing,  and  audit  concerns. 

SOFTWARE  PRODUCTS;  SUPPLEMENTAL  DOCUMENTATION 

1.  INTRODUCTION 

The  following  paper  describes  the  method  of  documenting  enhancements  to  established  software 
systems.  The  purpose  of  this  method  is  to  provide  a  consistent  pattern  of  analyzing  proposed 
modifications,  documenting  development  progress,  and  archiving  pertinent  project  documents.  The 
methodology  is  designed  to  provide  a  simple  structure  for  documenting  the  development  and 
implementation  of  enhancements  to  an  existing  system.  The  system  is  assumed  to  be  fully  documented 
in  its  own  right,  whether  a  privately  developed  program  or  a  marketed  software  product.  This  method 
is  supplemental  to  existing  documentation  for  such  programs  and  products.  Although  enhancements 
are  viewed  through  predefined  phases  or  categories,  necessary  attention  is  given  to  project  develop- 
ment, archival  documentation,  and  company  audit  concerns.  In  terms  of  new  systems  implementation, 
it  is  conceivable  that  this  straightforward  approach  will  find  applicability  for  shops  not  having  formal 
implementation  and  documentation  procedures  as  yet.  In  such  cases,  the  shop  will  find  it  necessary  to 
elaborate  on  the  basic  method  to  form  a  company's  complete  software  documentation  procedure. 

2.    DESIGN  CONSIDERATIONS 

The  Methodology  for  Supplemental  Documentation  of  Modifications  to  Software  Products  on  Small  to 
Medium  Sized  Systems  (SDMS)  developed  as  the  need  to  modify  formal  software  products  became 
necessary.  Such  products  have  their  own  documentation.  However,  no  method  was  available  for 
developing  and  implementing  modifications  to  the  products.  The  lack  of  such  an  approach  identified 
an  urgent  need.  SDMS  was  designed  for  the  ongoing  software  environment.  It  is  intended  to  document 
modifications  to  existing  systems.  The  approach  is  to  keep  the  method  basic  and  straightforward  while 
highlighting  such  historically  troublesome  areas  as  project  development  plan,  future  referencing,  and 
audit  (control)  concerns.  This  method  is  not  intended  to  replace  established  documentation 
procedures,  but  is  supplemental  in  nature.  It  is  designed  to  complement  current  procedures.  However, 
where  no  procedures  exist,  this  approach  (with  certain  additional  mandatory  inclusions)  offers  a  viable 
framework  for  custom  system  implementation  and  documentation. 

Software  products  are  designed  to  appeal  to  a  sufficiently  large  enough  market  to  justify  their  original 
development  costs.  Consequently,  it  is  their  nature  to  be  somewhat  broad  having  a  generalized  solution 
to  the  problem  they  address.  A  company  that  wishes  to  implement  such  software  products  must  either 
keep  their  current  systems  in  place  to  the  point  where  the  product  takes  control,  or  modify  their 
existing  systems,  or  modify  the  product  itself  to  accommodate  the  necessary  requirements  of  the 
company.  During  these  periods  of  review,  close  examination  is  often  given  to  the  company's  existing 
system  with  an  eye  toward  improvement.  Where  company  changes  are  needed,  company  procedures 
are  modified.  Where  systems  analysis  identifies  no  necessary  changes,  the  proposed  product  is 
evaluated  for  applicability  to  present  methods.  If  the  product  is  sufficiently  different  from  current 
procedure,  it  is  recommended  that  modifications  to  the  product  remain  close  to  the  original  product 
design.  The  final  form  of  the  system  undoubtedly  reflects  compromises  from  both  sides.  But  the 
rationale  is  that  any  modification  to  the  software  product  today  is  a  maintenance  task  tomorrow. 

SDMS  provides  not  so  much  a  concise  method  as  a  comfortable  framework  from  which  to  analyze  a 
proposed  need  for  product  modification,  describe  how,  what,  and  when  the  change  will  be,  and  retain 
permanent  records  of  the  developments  once  completed.  The  simple  structure  offers  ample  latitude 
for  existing  procedures  and  individual  initiative  while  providing  a  consistent  development  procedure. 

3.    PROCESS  DESCRIPTION 

The  user  recommends  a  change  to  MIS  by  completing  the  REQUEST  section  of  the  Project 
Implementation  form  (PI)  (Exhibit  A).  This  section  describes  in  general  terms  what  the  enhancement 
consists  of.  PI  is  submitted  to  MIS  development  for  consideration.  Requests  are  assigned  consecutive 
project  numbers.    An  initial  review  of  the  request  is  conducted  by  MIS  to  determine  reasonableness. 
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MIS  responses  from  this  initial  review  are  recorded  in  the  ACTION  section  of  the  PI.  The  project  is 
approved  for  analysis  and  feasibility,  or  disapproved  with  sufficient  reason. 

SDMS  consists  of  a  project-oriented  documentation  base.  Each  request  is  viewed  as  a  unique 
modification  except  in  cases  where  new  enhancements  add  to  or  obsolete  existing  modifications.  In 
such  cases,  project  number  revision  levels  are  incremented,  or  are  signified  inactive,  respectively. 
SDMS  control  derives  from  the  PI.  This  central,  uniform  document  summarizes  the  development 
process,  and  provides  basis  for  maintaining  a  standard  set  of  documentation  for  all  enhancements. 
This  document  highlights  the  development  plan  and  cross-references  additional  documents.  Project 
implementations  are  assisted  by  this  consistent  approach  to  the  development  process  through  the 
common  PI  reporting  format. 

Project  development  is  planned  by  MIS.  PI  allows  for  describing  a  project  in  seven  categories.  Based 
on  the  size  of  the  modification  and/or  standard  company  procedures,  these  categories  are  given  more 
or  less  attention  as  the  situation  dictates.  The  development  process  is  defined  by  these  phases- 
Existing  company  development  procedures  may  require  additional,  more  definitive  documentation. 
These  phases  represent  a  basic  logical  progression  in  development  thinking. 

3.1  Analysis 

User  requirements  are  defined.  Interviews  are  conducted  to  determine  project  requirements.  A 
preliminary  review  is  held  with  users  to  discuss  findings.  Project  definition  is  reworked  as 
required. 

3.2  Feasibility 

Reasonability  of  project  per  operational  and/or  economic  considerations  is  examined.  Pertinent 
information  is  gathered  and  analyzed.  The  impact  of  modification  per  operation  and/or  cost 
concerns  is  documented. 

3.3  Design 

Design  specifications  are  established.  Project  specifications  are  provided  with  necessary  support 
documents.  An  interim  review  is  held  with  programming  support  to  clarify  design  specifications. 

3A  Programming 

Modifications  are  coded  and  tested.  Programs  and  procedures  are  coded  per  design  specifica- 
tions. Flowcharts  and  logic  narratives  are  included  as  required. 

3.5  Evaluation 

Project  results  are  evaluated.  A  technical  review  of  project  is  held  with  programming  support. 
Project  goals  are  compared  to  results.  An  evaluation  is  held  with  a  user  review  board.  Attention 
focuses  on  project  objectives.  Review  board  either  recommends  implementation,  resubmits 
project  to  design  and  programming  phases,  or  decides  against  implementation. 

3.6  Implementation 

Implementation  plans  are  established.  A  firm  implementation  plan  is  developed.  Plan  is 
presented  to  users  for  approval.  Implementation  schedule  is  reworked  as  required. 

3.7  Postimplementation  Audit 

A  postimplementation  audit  is  conducted  to  determine  the  modification's  overall  effectiveness. 
Results  are  published  to  management. 

PROCESS  EVENTS 

This  section  summarizes  a  typical  series  of  events  comprising  the  development  process. 

't.l     Project  Action/Preliminary  Review 

The  PI  is  submitted  to  MIS  development.  Development  assigns  a  project  number  and  the  ACTION 
section  is  completed.  This  includes  the  reason,  a  description,  and  the  impact  of  the  modification 
on  current  environment.  Additional  support  documents  such  as  written  requests,  impact 
statements,  etc.,  are  referenced  in  the  reference  section  and  attached  to  the  form. 

Development  Approval/Project  Plan 

The  project  is  approved  for  development  by  MIS  management.  A  plan  is  established  including 
review  and  completion  dates,  assignments,  and  a  brief  description  of  each  phase  of  activity.  The 
PI  works  as  a  reference  document  during  analysis,  feasibility,  and  design  of  the  project. 
Supporting  documents  generated  during  these  phases  are  referenced  on  the  PI  and  attached. 
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Design/Interim  Review 

An  interim  review  with  programnning  support  is  conducted  during  the  design  phase  to  clarify 
project  goals  and  to  identify  conflicts  between  planned  design  and  coding  limitations. 

^■A     Programming/Technical  Review 

Development  releases  the  PI  to  programming  support  for  coding  and  testing.  Mandatory 
contributions  from  programming  activities  are  computer  listings  of  pertinent  procedures  and 
program  compilations.  These  are  referenced  on  the  PI  and  attached.  Programming  support 
releases  the  PI  to  development  during  evaluation.  Overall  project  goals  and  test  results  are 
reviewed  by  analysts  with  programming  support  from  a  technical  perspective. 

1^.5     User  Evaluation/Implementation 

Development  presents  project  results  to  the  review  board  for  evaluation.  The  review  board  is 
comprised  of  user  groups  and  MIS  management.  Implementation  follows  a  favorable  review  and 
appropriate  approvals. 

it.f)     Document  Package  Creation/Backup 

Projects  are  recorded  in  one  of  two  indices — one  indexing  nonimplemented,  the  other  imple- 
mented (Exhibit  B). 

The  attachment  of  all  supporting  documents  referenced  on  the  PI  is  verified.  The  originals  and 
duplicates  of  the  PI  and  all  attachments  are  brought  together  as  document  package  and  backup, 
respectively.  The  original  is  retained  in  MIS  local  files.  The  duplicate  is  archived  off-site. 
Proper  assemblage  of  the  packages  is  verified  by  a  second  party. 

1^.7     Postimplementation  Audit 

Several  months  after  implementation,  an  audit  of  the  modification  is  done.  Project  goals  are 
reviewed  for  the  effectiveness  of  modifications,  and  any  subseqent  problems  are  examined  and 
documented.  Audit  results  are  included  in  the  document  package,  and  published  to  management. 

5.    PR03ECT  IMPLEMENTATION  FORM 

5.1  Request  Section 

The  REQUEST  section  identifies  the  individual  requesting  a  change  or  modification  and  the  date 
of  the  request.  A  description  of  the  change  from  the  user's  perspective  is  given,  and  a  statement 
summarizing  the  need  for  change. 

5.2  Action  Section 

The  ACTION  section  identifies  the  individual  originating  the  project  and  the  date  of  the 
origination.  MIS  personnel  are  responsible  for  project  number  generation  and  control.  A  project 
number  and  any  subsequent  revision  is  assigned.  A  description  of  the  modification  views  the 
change  from  a  technical  perspective.  Effects  on  the  current  environment  are  highlighted.  The 
request  is  examined  to  determine  what  specific  library  elements  and  data  files  would  be  altered 
by  enhancements.  The  degree  of  the  change  is  given  in  terms  of  lines  of  code  changed  or  added. 
Dynamic  procedural  impacts  are  also  described.  A  formal  impact  statement  may  be  required.  If 
so,  it  is  identified  in  the  REFERENCE  section.  Any  impact  on  costs  and  schedules  is  described. 
The  individual  reviewing  the  request  is  identified  and  the  date  of  the  review.  The  review  either 
accepts  the  request  for  development,  or  rejects  it.  If  rejected,  sufficient  reason  is  given. 

5.3  Development  Section 

The  DEVELOPMENT  section  describes  the  goals  of  each  particular  phase  or  category  of  the 
development  process.  Tentative  completion  dates  and  specific  deliverables  are  given  for  each. 
Responsibility  for  the  three  mandatory  reviews  is  assigned.  Possible  inclusions  at  each  point 
might  be: 

Analysis  -       Statement  of  project  scope,  system  surveys,  and  analyses  of 

project  requirements. 

Feasibility  -       Feasibility  studies. 

Design  -       System  schematics,  job  stream  descriptions,  design  narratives, 

and  file  layouts. 

Programming  -        Flowcharts,  and  logic  narratives. 

Evaluation  -        User  evaluation  reports. 
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Implementation 


Detailed  implementation  schedule. 


Postimplementation     -        Audit  report. 
5A     Control  Section 

The  CONTROL  section  identifies  proper  PI  completion,  respective  Project  Number  Index  entry, 
mandatory  inclusion  of  computer  compilations  and  procedure  listings,  attachment  of  all 
referenced  documents,  proper  assemblage  of  the  document  package,  and  the  reverif ication  of  the 
foregoing  by  a  second  party.  Verification  is  signified  by  initialing.  Development  and 
implementation  are  each  approved  by  MIS  management. 

5.5     Reference  Section 

The  REFERENCE  section  identifies  by  name  each  document  referenced  and  attached  throughout 
the  development  process  to  form  the  document  package. 

6.    PROJECT  NUMBER  INDEX  FORM 

The  Project  Number  Index  includes  an  entry  for  each  project  number/revision  level  occurrence.  The 
date  of  the  entry,  plus  libraries,  elements,  element  types,  and  number  of  lines  changed  or  added  is 
given.  The  individual  logging  the  entry  is  identified  along  with  a  brief  description  of  the  modification. 
It  is  recommended  that  the  Index  be  stored  on  disk,  and  that  retrieval  consist  of  two  or  three  reversing 
formats  as  the  MIS  function  has  need. 

7.    GENERAL  CONSIDERATIONS 

7.1     Document  Package 

Control  of  modification  documentation  derives  from  the  PI.  Pertinent  supporting  documents  are 
logged  in  the  REFERENCE  section  of  the  PI.  This  group  of  documents  represents  the  Document 
Package.  Contents  vary  from  project  to  project.  However,  a  certain  number  of  mandatory 
inclusions  are  necessary.  They  include  program  compilations  and  procedure  listings.  It  is 
recommended  that  design  narratives  describing  basic  system  flow  be  provided  for  anything 
beyond  minor  modifications.  The  comprehensiveness  of  the  Document  Package  is  determined  by 
the  impact  of  enhancements  to  the  existing  environment.  All  attachments  are  identified  by  a 
PROJECT  DOCUMENT  stamp. 


PROJECT  DOCUMENT 

PROJECT  NO   REV   

DATE   TOTAL PGS  

SUBMITTED  BY  .  


Shops  using  this  methodology  as  their  documentation  base  should  require  as  mandatory  inclusions 
such  things  as  analysis  and  design  narratives,  feasibility  studies,  system  schematics,  file  layouts, 
logic  narratives,  and  detailed  implementation  schedules. 

7.2     Composition  of  Project  Number 

Some  thought  should  be  given  to  the  method  of  assigning  project  numbers.  It  is  recommended 
that  the  composition  of  the  project  number  be  comprised  of  three  parts.  The  first  portion  to 
represent  the  application  affected  by  the  modification.  The  second  portion  to  represent 
sequential  numbering  of  projects,  and  the  third  portion  to  represent  subsequent  revisions  to 
projects. 


AP    101  01 


REVISION  LEVEL 
CONSECUTIVE  NUMBER 
APPLICATION  CODE 


The  composite  project  number  of  the  above  example  is  APIOIOI.  This  allows  for  grouping  by 
application  and  permits  distinct  filing  for  each  revision  level. 
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7.3     PARALLELING  ACTIVITIES 


The  development  process  requires  the  timely  participation  of  all  involved.  The  PARALLELING 
STRUCTURE/LEVEL/PHASE  diagram  (Exhibit  C)  illustrates  this  process  of  coordination  between 
each  function  and  phase,  and  how  they  coincide  with  the  SDMS  methodology. 

8.  CONCLUSION 

The  SDMS  methodology  adopts  a  simple,  straightforward  approach  to  the  development  of  modifications 
for  software  products.  It  has  potential  as  the  basis  for  complete  system  documentation.  However,  its 
primary  thrust  is  as  a  supplement  to  existing  documentation.  Design  concerns  consist  of  maintaining 
method  simplicity  and  a  supplemental  nature  to  the  scheme.  Practical  problems  occurring  during  the 
implementation  of  changes  are  reviewed.  A  general  framework  rather  than  a  concise  formula  is 
established  for  identifying  control  points  within  the  development  process. 

The  process  is  divided  into  seven  categories:  Analysis,  Feasibility,  Design,  Programming,  Evaluation, 
Implementation,  and  Postimplementation  Audit.  Each  category  is  described  and  a  typical  series  of 
development  process  events  is  presented.  The  movement  of  forms  and  supporting  documents  plus 
various  approvals  and  reviews  is  described.  The  use  of  two  forms  is  discussed  in  detail.  The  Project 
Implementation  (PI)  form  serves  as  the  control  document  for  the  whole  of  SDMS.  The  Project  Number 
Index  simply  indexes  the  many  projects. 

Several  general  considerations  are  discussed  including  the  formulation  of  a  Document  Package,  a 
suggested  composition  for  the  project  number,  and  a  diagram  illustrating  dynamics  of  development 
process  interplay. 
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Operations  Documentation  Standards  -- 
Online,  Real-time  Versus  Offline,  Batch 


Deborah  A.  Harman 
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Dublin,  Ohio  43017 


The  FIPS  38  content  guidelines  for  the  Operations  Manual  should  include  or 
expand  four  topics  important  to  real-time  processing:    hardware  configuration; 
start-up,  shutdown,  and  performance  monitoring  procedures;  error  messages;  and 
non-routine  procedures. 


Keywords:    Documentation;  Operations  manual;  Real-time  system. 


1.  INTRODUCTION 

The  operations  documentation  developed  for  an  offline,  batch  system  must  be  somewhat 
different  from  that  developed  for  an  online,  real-time  system.    Offline,  batch  processing, 
besides  being  the  simplest  and  cheapest  form  of  processing,  also  requires  far  less  operator 
training  and  support  than  does  real-time  processing.    Real-time  systems  are  installed  to 
satisfy  users'  needs  for  immediately  updated  information. [1]    While  some  errors  and  reruns 
can  be  accommodated  in  a  batch  environment,  the  users'  total  dependence  on  the  system  in  a 
real-time  environment  makes  any  service  disruption  i ntol erabl e.[2]    Operators  must  be 
prepared,  both  through  training  and  documentation,  to  respond  immediately  to  real-time 
processing  problems. 

This  need  for  operator  responsiveness  to  ensure  real-time  system  availability  is  not 
adequately  addressed  in  FIPS  38.  Specifically,  the  content  guidelines  for  the  Operations 
Manual  should  be  revised  to  include  or  expand  the  following  topics: 

.    Hardware  configuration 

.    Start-up,  shutdown,  and  performance  monitoring  procedures 

Error  messages 
.    Non-routine  procedures 


2.    OCLC'S  OPERATIONS  DOCUMENTATION  ■ 

2.1    Batch  and  Online  System  Documentation  at  OCLC 

Some  of  the  same  weaknesses  found  in  the  FIPS  38  Guidelines  have  been  revealed  in  the 
documentation  prepared  for  the  operators  of  the  OCLC  Online  System.    Our  experience  in 
evaluating  and  revising  this  documentation  is  offered  here  in  the  hope  that  it  may  save 
others,  creating  documentation  for  an  interactive  system,  some  time  and  expense. 
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OCLC  provides  bibliographic  resource  sharing  and  support  services  to  over  4,400 
terminals  in  5,000  libraries  throughout  the  United  States,  Canada,  Mexico,  and  Great 
Britain.    Through  the  OCLC  telecommunications  network,  lilDraries  can  access  and  update  a 
data  base  consisting  of  eight  million  catalog  records.    Shared  use  of  OCLC's  online  data 
base  relieves  libraries  of  the  necessity  to  perform  many  manual,  labor-intensive  tasks  and 
helps  libraries  to  reduce  rising  costs  and  to  improve  services.    Because  of  the  importance 
of  system  availability  and  response  time  to  its  member  libraries,  OCLC  carefully  monitors 
the  performance  of  the  Online  System. 

Not  surprisingly,  OCLC  places  far  greater  emphasis  on  the  documentation  prepared  for 
its  online  processing  than  on  that  prepared  for  its  batch  operations.    Not  that  OCLC's  batch 
operations  are  trivial;  each  week,  the  Production  System  generates,  among  other  things,  2.5 
million  catalog  cards  for  shipment  to  libraries.    However,  standards  for  batch  operating 
procedures  are  only  now  being  developed,  and  the  batch  documentation  itself  exists  in  a 
variety  of  forms  (including  notes  and  memoranda).    An  i nterdi vi si onal  effort  is  underway  to 
address  batch  documentation  problems.    In  contrast,  OCLC  has  prepared,  for  the  Online  System 
operators,  an  enormous  volume  of  material  —  the  Systems  Operations  Reference  Manual  (SORM) 
--  450  pages  in  length. 

2.2  The  Operations  Manual  Questionnaire 

The  Systems  Operations  Reference  Manual,  originally  released  in  1979,  is  revised 
quarterly  by  the  Documentation  Department  of  OCLC  to  reflect  software,  hardware ,. and 
procedural  changes  affecting  the  Online  System.    Late  last  summer,  wondering  whether  our 
revision  efforts  might  be  better  directed,  we  prepared  a  questionnaire  posing  for  evaluation 
32  specific  statements  about  the  manual's  completeness,  accuracy,  content,  organization, 
style,  and  format.    This  questionnaire  was  distributed  to  70  holders  of  the  SORM. 

It  was  encouraging  to  learn  from  the  responses  to  the  questionnaire  that  the  holders  of 
the  SORM  were  actually  using  it;  in  fact,  most  of  the  computer  operators  indicated  that  they 
were  referring  to  the  manual  on  a  daily  basis.    However,  the  evaluative  responses  to  the 
questionnaire  were  less  than  enthusiastic.    Initially,  it  seemed  impossible  to  form  a 
revision  plan  to  resolve  all  the  problems  noted  by  the  respondents  to  the  questionnaire. 
Finally,  by  selecting  only  statements  to  which  over  half  of  the  respondents  had  expressed 
strong  agreement  or  disagreement,  we  were  able  to  identify  those  aspects  of  the  manual 
requiring  immediate  attention.    Unfortunately,  the  major  problem  area  was  the  material 
itself;  respondents  indicated  that  the  information  in  the  SORM  was,  in  some  cases,  outdated 
and,  in  general,  incomplete.    Specifically,  they  suggested  the  following  topics  for 
inclusion  or  expansion  in  the  manual: 

Overview  of  the  OCLC  Online  System 
.    Online  System  Responsibilities  by  Position  and  Organizational  Unit 
Hardware  Description  and  Operation 
Recovery  Procedures 
Problem  Detection  and  Resolution 
Emergency  Priorities 
Safety  and  Security  Procedures. 

2.3  Addressing  Problems  in  OCLC's  Operations  Manual 

The  problem  of  outdated  information,  though  serious,  is  not  difficult  to  resolve. 
Auditing  current  practices  in  the  Data  Center  against  documented  procedures  should  identify 
specific  items  requiring  correction  in  the  manual.    Better  control  procedures,  to  verify 
that  revision  material  is  prepared  as  system  changes  are  implemented,  will  also  help  to  keep 
the  SORM' s  content  current. 

However,  the  problem  of  incompleteness  will  be  costly  to  resolve,  since  eventually  it 
will  necessitate  the  total  reprinting  of  the  manual.    Among  the  topics  suggested  for 
expansion,  only  the  last  two  --  Emergency  Priorities  and  Safety  and  Security  Procedures  — 
are  not  included  at  all  in  the  current  manual.    Althougli  these  topics  are  covered  in  the 
corporate  standards  manual,  they  do  need  to  be  detailed  specifically  in  terms  of  Data  Center 
operations,  and  will,  therefore,  be  added  to  an  administrative  portion  of  the  manual. 
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The  remaining  topics  require  more  emphasis  and  detail  than  presently  offered.  This 
will  necessitate  not  only  adding  new  material,  but  also  reorganizing  existing  information. 
For  example,  all  error  messages  are  now  listed  with  their  page  references  at  the  end  of  the 
SORM,  but  the  explanations  and  appropriate  operator  responses  for  the  messages  are  scattered 
throughout  the  text  of  the  manual.    A  computer  operator  may  need  to  flip  from  one  section  of 
the  manual  to  another  to  understand  clearly  what  a  given  error  message  means  and  what  he 
should  do  about  it.    An  obvious  first  step  in  revising  the  manual  is  to  place  all  the 
information  concerning  the  messages  in  a  single  appendix.    Similarly,  recovery  procedures 
and  instructions  for  detecting  and  resolving  problems  are  located  in  several  sections  of  the 
manual.    Separate,  clearly  defined  sections  --  Performance  Monitoring  Procedures  and 
Restart/Recovery  Procedures  --  will  be  added. 


3.  CONCLUSIONS 

3.1  OCLC's  Documentation  and  FIPS  38 

The  needs  expressed  by  OCLC's  Online  Operations  staff  are  typical  of  the  needs  of  all 
operators  working  in  a  real-time  system  environment.    The  FIPS  38  content  guidelines,  to 
some  extent,  imply  the  inclusion  of  such  topics  as  those  listed  by  the  users  of  OCLC's 
manual.    However,  these  topics  must  be  identified  separately  and  highlighted  as  part  of  the 
Operations  Manual  to  ensure  the  availability  of  this  information  to  operators  when  they  need 
it.    Careful  consideration  of  operators'  needs  in  advance  of  publication  will  reduce  the 
need  for  major  subsequent  revisions. 

3.2  Hardware  Configuration 

FIPS  38  should  be  revised  to  specify  a  discussion  of  hardware  as  part  of  the  Operations 
Manual.    Possibly,  in  a  batch  environment,  no  detailed  discussion  of  hardware  is  necessary; 
where  the  same  or  similar  equipment  is  likely  to  be  used  for  all  processing,  vendor 
documentation  may  be  enough.    However,  online  systems  typically  have  multi-vendor  hardware 
configurations,  and,  when  problems  arise,  response  time  may  well  be  dependent  on  the 
operator's  understanding  of  the  equipment.    In  an  online,  real-time  system,  there  is  also  no 
batch  job  ticket  to  indicate  to  the  operator  which  machines  are  used  for  running  any  given 
program.    Therefore,  Hardware  Configuration  should  be  added  to  the  OVERVIEW  Section,  as 
paragraph  2.1,  with  the  subsequent  topics  renumbered  accordingly,  e.g.,  2.2  Software 
Organization.    The  discussion  factors  for  the  2.1  Hardware  Configuration  paragraph  need  not 
be  very  different  from  those  suggested  for  the  discussion  of  Equipment  in  the  other  document 
types.    The  following  guideline  for  discussion  factors  might  provide  useful  background 
information  to  operators: 

Identify  the  equipment  required  for  the  operation  of  the  system.  Describe 
any  significant  operating  features,  such  as  the  function  and  use  of 
lights,  switches,  and  keys.    Relate  the  hardware  to  specific  processing 
functions  or  applications.    When  appropriate,  provide  a  diagram  showing 
functional  relationships  between  mainframes,  communications  controllers, 
and  peripheral  devices. 

3.3  Start-up,  Shutdown,  and  Performance  Monitoring  Procedures 

FIPS  38  should  also  be  revised  to  specify  system  start-up,  shutdown,  and  performance 
monitoring  procedures.    These  procedures  should  be  included  as  separate  paragraphs  for 
discussion  in  Section  3,  DESCRIPTION  OF  RUNS.    Start-up,  shutdown,  and  monitoring  procedures 
can  be  viewed  as  types  of  runs,  but  in  an  online,  real-time  environment,  they  may  also  be 
the  only  clearly  identifiable  routine  jobs,  and  thus  merit  special  attention.    The  complex 
sequence  of  operator  actions  required  for  system  start-up  and  shutdown  and  the  importance  of 
timely  problem  detection  also  suggest  that  specific  mention  (as  paragraphs  3.1,  3.6,  and 
3.7)  is  appropriate  in  the  content  guidelines. 
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3.4  Error  Messages 

A  list  of  all  error  messages  should  be  added  to  the  end  of  Section  3.    This  list  could 
be  organized  in  any  way  appropriate  for  the  particular  system,  but  should  include  such 
information  as: 

an  explanation  of  the  error  message; 
.    identification  of  the  process  or  program  generating  it; 
.    an  indication  of  its  severity; 

.    action  or  response  required  of  operations  personnel. 

Consolidating  this  information  tovwrd  the  end  of  the  Operations  Manual  would  make  it 
more  accessible  to  operations  personnel  and  could  result  in  less  downtime.    The  list  creates 
some  redundancy  in  the  contents  of  the  Operations  Manual,  in  that  it  repeats  messages 
included  in  the  Run  Description.    However,  the  potential  benefits  of  such  a  list  outweigh 
the  inconvenience  of  maintaining  duplicate  information. 

3.5  Non-Routine  Procedures 

Section  4  of  the  content  guidelines  should  be  expanded  to  emphasize  the  control 
responsibilities  of  operations  personnel.    The  following  outline  suggests  one  form  such  an 
expansion  might  take: 

4.    NON-ROUTINE  PROCEDURES 

4.1.  Emergencies  and  System  Failures. 

Identify  types  or  causes  of  potential  system  failures  and 
emergencies.    Define  for  each  the  responsibilities  of 
operations  personnel.    Include  such  information  as  the 
features  and  operation  of  safety/security  devices;  emergency 
priorities;  and  problem  reporting  procedures. 

4.2.  Switchover  to  a  Back-up  System. 

Describe  any  available  back-up  systems  and  the  conditions  and 
procedures  for  their  use. 

4.3.  Turnover  to  Support  Groups. 

Describe  the  conditions  and  procedures  for  transferring 
responsibility  for  operation  of  the  system  to  appropriate 
support  groups,  such  as  maintenance  programmers,  computer 
engineers,  network  control  analysts,  testing  and  installation 
staff,  etc. 

Although  some  of  this  information  might  be  more  pertinent  in  an  administrative  manual, 
including  it  in  the  Operations  Manual  would  ensure  its  availability  to  computer  operators. 
Content  guidelines  reflecting  the  need  for  safety,  security,  and  contingency  procedures 
should  minimize  the  occurrence  of  disasters  and  the  time  required  to  recover  from  them. 

3.6  Benefits  of  Revised  Content  Guidelines 

The  four  revisions  to  the  Operations  Manual,  outlined  here,  stress  the  need  for 
increased  understanding  and  awareness  on  the  part  of  operations  personnel  in  an  online 
system  environment.    As  Guldentops  has  observed,  "Operating  online  systems  often  becomes  a 
tedious  and  boring  job  needing  few  interventions  and  little  initiative,  but  requiring 
constant  al ertness. "[3]    Although  actual  operating  tasks  become  simpler,  the  required 
knowledge  and  skill  level  necessary  to  ensure  high  system  performance  become  more  complex. 

Attention  to  the  needs  of  the  operations  audience  —  both  batch  and  online  --  should 
result  in  better  system  performance  and  fewer  documentation  revisions. 
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Documentation  for  Operation  Phase 
of  Systems  Life  Cycle 

Robert  A.  Larson 

USDA,  Forest  Service 

This  paper  is  on  software  documentation  requirements  during  the  Operation  Phase 
of  automated  systems  life  cycle  in  the  Forest  Service.  Implementation  of  these 
requirements  was  started  in  1978.  This  encompassess  some  five  thousand  programs 
in  a  distributed/dispersed  environment.  The  Forest  Service  has  a  systems 
management  process  covering  the  systems  life  cycle  which  includes  this  phase. 
This  process  has  been  implemented  in  our  national  and  field  offices  with 
significant  success. 

The  documents  to  be  presented  come  from  the  Forest  Service  Systems  Management 
Manual  and  Automated  Systems  Management  and  Documentation  Handbooks.  This  paper 
covers  the  document  contents,  associated  experiences  and  future  plans  for 
managing  software  in  the  Operation  Phase. 

1.  INTRODUCTION 

The  Forest  Service,  U.  S.  Department  of  Agriculture,  has  primary  responsibility  for 
protection  and  management  of  this  nation's  forest  resources.  There  are  three  operating 
divisions:  one  is  charged  with  the  management  of  approximately  187  million  acres  of 
federally-owned  National  Forests,  a  second  promotes  forestry  on  state  and  private  lands, 
and  a  third  is  a  research  arm.  The  Forest  Service  is  comprised  of  9  National  Forest 
Regions,  2  State  and  Private  Forestry  Areas,  8  Research  Stations  and  a  Forest  Products 
Laboratory.  Each  Region  has  from  13  to  20  National  Forests  and  each  Forest  has  from  4  to 
6  Ranger  Districts.  In  total  there  are  123  National  Forest  offices  and  653  Ranger 
District  offices  within  the  Forest  Service. 

Forest  Service  management  is  delegated  to  the  lowest  appropriate  level.  It  is  essential 
that  computing  resources  be  provided  to  all  organizational  levels  and  that  these 
resources  be  prudently  managed.  The  central  host  computer  used  by  the  Forest  Service  is 
a  UNI  VAC  1100/84  located  in  Fort  Collins,  Colorado.  The  Forest  Service  also  has 
computing  and  word  processing  facilities,  including  stand-alone  facilities,  located  in 
the  National  Headquarters,  Region,  Area  and  Station  offices,  most  Forests,  and  many 
Ranger  Districts.  There  is  a  wide  variety  of  outside  computer  usage  through  contracts 
and  cooperative  agreements  with  major  universities.  Most  of  the  in-house  facilities 
communicate  with  or  through  the  host  computer  and  range  from  non-intelligent  terminals  to 
full  size  computers.  These  facilities  provide  for  the  development  and  use  of  over  5000 
programs  in  a  distributed/dispersed  environment. 

In  1976  the  Forest  Service  created  a  new  Systems  Mangement  organization  as  the  result  of 
a  study  having  input  from  management,  users,  and  computer  specialists.  Three  areas  of 
need  identified  and  emphasized  in  that  study  were  for  systems  standards,  documentation 
requirements  and  improved  systems  management.  The  Forest  Service  successfully 
implemented  a  systems  management  process  covering  the  total  systems  life  cycle  in  1977. 

Some  standards  and  guidelines  had  been  drafted  by  both  in-house  resources  and 
consultants,  but  had  not  been  implemented  prior  to  January  1977.  This  material  along 
with  FIPS  PUB  38  and  DOD's  Documentation  Standards  were  used  in  developing  the  Forest 
Service  documentation  handbook.  The  work  was  accomplished  through  workshops  and  the  use 
of  personnel  detailed  from  field  units  on  specific  project  assignments  to  assure  field 
input.  Management  and  technical  staffs  at  all  organizational  levels  reviewed  the 
completed  work  and  it  was  published  in  November,  1978. 
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This  paper  presents  Forest  Service  documentation  requirements  for  the  Operation  Phase  of 
the  Systems  Life  Cycle.  Several  existing  systems  have  been  brought  into  the  management 
process  and  into  compliance  with  standards  using  these  requirements. 

Documentation  is  a  key  software  mangement  tool  where  both  management  and  data  processing 
facilities  are  widely  dispersed.  Our  management  process  uses  this  documentation  to 
support  management  and  technical  reviews  throughout  the  systems  life  cycle  (Figure  1). 

2.  RECOMMENDATION 

There  is  a  need  for  consistent  Government-wide  guidelines  and  standards  covering 
documentation  requirements  in  all  phases  of  the  systems  life  cycle.  Currently  only  the 
Initiation  and  Development  Phases  are  covered  by  FIPS  PUB's.  There  are  strong 
indications  that  FIPS  PUB  38  needs  to  be  updated.  The  Forest  Service  is  in  the  process 
of  updating  their  documentation  requirements  for  all  phases  including  the  Operation  Phase. 

The  purpose  here  is  to  present  Operation  Phase  documentation,  how  it  is  being  used  and 
its  effectiveness.  The  recommendation  is  that  similar  requirements  or  quidelines  could 
and  should  be  applied  Government-wide  at  an  early  date.  The  Forest  Service  documents, 
after  inclusion  of  proposed  improvements,  could  be  used  as  a  starting  point  for 
development  of  a  FIPS  PUB  Guideline  for  Operation  Phase  Documentation. 

3.  DISCUSSION 

The  Operation  Phase  starts  immediately  following  formal  system  acceptance  by  users  and 
management.  The  first  step  is  full  implementation  following  an  approved  Implementation 
Plan.  It  is  preferred  that  a  system  be  certified  prior  to  this,  but  this  has  not  always 
been  possible.  Completion  of  the  Operation  Phase  occurs  with  a  management  decision  to 
remove,  replace  or  extensively  modify  the  system.  In  the  event  of  replacement  or 
extensive  modification  the  system  should  cycle  back  to  the  Initiation  or  Development 
Phase. 

The  documentation  requirements  have  not  seen  as  much  use  as  anticipated,  but  what  the 
Forest  Service  has  seen  is  quite  promising.  Some  of  the  improvements  needed  will  be 
covered  later  in  this  discusssion.  The  primary  software  management  documents  involved 
with  this  phase  are  as  follows: 

1.  Automated  Systems  Certification 

2.  Problem  Report/Modification  Request 

3.  Periodic  Review  and  Evaluation 

4.  In-depth  Review  Plan 

5.  In-depth  Review  and  Evaluation 

These  documentation  requirements  have  assisted  the  Forest  Service  in  cleaning  up  their 
libraries,  bringing  systems  up  to  standard,  reducing  maintenance  and  improving  the 
quality  of  existing  systems. 

The  Project  Acceptance  document  which  is  signed  prior  to  implementation  does  not  assure 
that  the  system  is  certifiable.  In  fact,  in  most  instances  there  is  still  significant 
work  to  be  done  prior  to  certification.  It  does  provide  assurance  that  the  system  is 
acceptable  and  has  the  approval  of  management  to  be  fully  implemented.  Management  can 
then  allow  a  reasonable  time  frame  to  meet  the  certification  requirements  while 
implementation  is  progress.  There  are  few  certified  systems  to  date,  but  the  Automated 
Systems  Certifications  (Figure  2)  was  not  required  for  new  systems  until  about  a  year 
ago.  This  document  and  other  modifications  were  a  result  of  attempting  to  assure 
compliance  with  Departmental  and  Forest  Service  requirements.  There  has  been  a  fair 
start  towards  doing  just  that. 
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The  Problem  Report/Modification  Request  (Figure  3)  with  associated  procedures  and 
requirements  were  placed  in  effect  about  the  same  time  as  the  certification  document. 
This  is  a  record  of  problems  and  modifications  and  the  appropriate  action  taken.  Prior 
to  this  there  were  complaints  of  problems  reported  and  modifications  requested  for  which 
there  was  no  apparent  response  from  the  system  support  staff.  Some  were  legitimate,  some 
were  not,  but  there  was  no  documented  evidence  one  way  or  the  other,  if  this  document 
has  done  nothing  else,  it  has  improved  communications  between  the  end  users  and  the 
support  staff. 

Other  maintenance  procedures  and  documents  may  be  used,  but  they  must  first  be  approved. 
Also,  the  alternative  requirements  and  procedures  must  be  included  in  the  user  and 
maintenance  manuals.  With  this  direction  there  has  been  noted  improvement  of  systems 
maintenance  records  including  the  documentation  of  changes.  Much  more  needs  to  be  done 
but  it  is  a  good  start.  More  people  are  now  getting  involved  and  are  looking  for  further 
improvements. 

One  problem  in  the  past  was  obsolete,  undocumented  and  low  usage  programs  in  our 
libraries.  To  deal  with  this  a  requirement  was  established  for  periodic  (minimum  of  once 
per  year)  review  of  all  systems.  With  this  a  Periodic  Review  and  Evaluation  document 
(Figure  4)  was  developed  and  mandatory  review  criteria  identified.  This  document  was 
only  partially  successful,  but  it  served  to  point  out  things  to  look  for  in  existing 
systems. 

The  Forest  Service  is  now  looking  at  modifying  the  periodic  review  requirements  and 
associated  documents.  This  will  involve  partially  automating  the  process  by  providing  an 
annual  report  showing  computer  resource  utilization,  summary  of  problems  and  modification 
requests,  and  support  staff  comments  for  each  system.  This  review  will  not  require 
interviews  or  significant  user  involvement.  Most  of  the  burden  of  preparing  this  report 
falls  on  the  systems  support  staff. 

Based  on  a  current  need  or  the  results  of  a  periodic  review,  management  may  request  an 
in-depth  review.  This  review  covers  many  of  the  same  criteria  as  acceptance  testing  with 
heavy  involvement  of  the  developer,  user,  and  management  personnel.  This  review  also 
looks  at  current  needs  and  the  system  environment.  An  in-depth  review  may  replace  a 
periodic  review. 

The  extensi veness  of  an  in-depth  review  and  the  significance  of  resources  utilized  for 
that  review  requires  an  approved  In-depth  Review  Plan  (Figure  5)  prior  to  the  review. 
Upon  completion  of  the  review,  an  In-Depth  Review  and  Evaluation  Report  (Figure  6)  is 
presented  to  management.  Management's  decision  at  this  point  will  be  to  (1)  remove  the 
system,  (2)  approve  continuance,  (3)  approve  modification,  or  (4)  approve  replacement. 

This  review  has  been  effective  in  bringing  existing  systems  into  the  management  process. 
It  has  also  created  a  management  awareness  that  was  not  there  before. 

The  Forest  Service  is  currently  looking  into  simplifying  the  process  for  review  of 
smaller  systems.  To  date,  primary  usage  has  been  on  large  systems  with  identified 
problems  or  potential  modification  requirements. 

This  completes  coverage  of  all  of  the  required  operation  phase  documents  except  for  the 
review  criteria.  The  review  criteria  are  key  to  the  pilot  test,  periodic  and  in-depth 
reviews  and  to  system  certification.  Some  users  would  like  simple  criteria  like  "does  it 
run",  but  there  is  more  to  it  than  that.  Major  review  criteria  categories  are  identified 
in  Figure  7.  Figure  8  contains  an  example  of  detailed  criteria  for  one  category.  Other 
systems  dependent  or  management  specific  criteria  may  be  added  to  this  list  for  any  of 
the  reviews.  Certification  or  recertif ication  of  a  system  requires  full  compliance  with 
the  mandatory  pilot  test  criteria. 
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At  the  time  these  requirements  were  established  there  was  very  little  reference  material 
available  or  experience  to  draw  from.  FIPS  PUB  standards  or  guidelines  would  have  been 
used  if  they  had  been  available.  The  wheel  should  not  have  to  be  re-invented.  Any  NBS 
efforts  to  publish  standards,  guidelines,  procedures,  covering  this  segment  of  the  data 
processing  area  should  be  supported.  The  sooner  they  can  do  this  the  better,  easier  and 
more  cost  effective  it  will  be  for  all  concerned.  There  should  also  be  more  flexibility 
and  a  faster  release  of  new  material  and  updates.  Several  standards  and  guidelines  in 
the  past  have  been  obsolete  before  they  were  published. 

4.  CONCLUSION 

Forest  Service  Operations  Phase  documentation  requirements  are  far  from  perfect. 
However,  they  provide  a  good  basis  from  which  to  start.  With  their  past  experience  and 
that  of  others,  the  Forest  Service  hopes  to  significantly  improve  their  requirements  in 
this  phase  of  the  systems  life  cycle. 

To  effectively  develop  and  implement  data  processing  standards  and  guidelines  it  takes  a 
concerted  effort  by  management,  developers  and  users.  Without  management  backing  many 
individuals  will  not  read  or  use  the  material  although  it  is  to  their  benefit  and  that  of 
the  organization.  Even  with  management  backing  the  implementation  process  can  be  slow 
and  sometimes  painful. 

As  stated  at  a  recent  standards  workshop,  the  six  E's  (Establish,  Educate,  Encourage, 
Enforce,  Evaluate,  and  Enhance)  are  required  for  successful  implementation  and  use  of 
standards  and  guidelines.  The  weakest  areas  are  Education  and  Encouragement.  This  is 
often  due  to  insufficient  resources  such  as  people  and  money  to  do  it  effectively. 
Everyone  is  familiar  with  Establish  and  Enforce.  In  fact,  so  familiar  that  the  need  for 
emphasizing  Evaluation  and  Enhancement  is  overlooked  .  The  Forest  Service  anticipates 
Enhancement  to  the  periodic  reporting  process  and  documentation  in  the  near  future.  With 
that  to  be  more  effective,  they  are  planning  to  improve  on  the  Education  and  Encouragment 
of  their  staffs  and  management. 
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AUTOMATED  SYSTEM  CERTIFICATIONS 


SYSTEM  NAME 


SYSTEM-ID  (3-Chdr.) 


In  addition  to  the  approvals  which  have  been  given  to  the  development 
stages  for  this  system,  the  following  specific  certification  are 
documented  for  the  system  record: 


TECHNICAL  ASSURANCES 

The  accuracy  of  modeling  assumptions  and  the  algorithms  of  the 
system  are  deemed  to  be  appropriate.    Assurances  that  all  applicable 
national  standards  and  security  requirements  have  been  met  are 
hereby  provided. 


SYSTEM  CERTIFICATION 

Certification  of  the  adequacy  of  security  requirements  (such  as: 
FSH  6609.33,  OMB  Cir.  No.  A-71),  National  Standards  Compliance, 
Modeling  Assumptions,  algorithms,  and  documentation  is  hereby 
provided. 


Director,  Support  Staff 


Date 


Associate  Deputy  Chief  for  Administration 


Date 


Figure  2 
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U.S.  Department  of  Agriculture 
Forest  Service 

AUTOMATED  SYSTEM  PROBLEM  REPORT/MODIFICATION  REQUEST 

(Instructions  Reference  FSM  6620) 

PART  I  -  REQUESTING  UNIT 

1 .  Originator's  Name 

2.  Unit 

3.  Date 

4.  Address  (Include  City,  State,  and  Zip  Code) 

5.  System  Name 

6.  System  \D  (3  characters) 

7.  Type  of  Request  (X  appropriate  box) 

1    1  Problem  or  Error                                             Suggested  Modification 

1    1  Information  Only 

8.  Description 

9.  Materials  Attached 

PART  II  -  SUPPORTING  UNIT 

1.  Evaluator's  Name 

2.  Date  of  Evaluation 

3.  Evaluation 

4.  Estimated  Cost 

5.  Action  Taken 

6.  Actual  Cost 

7.  Action  Taken  By                                                                                    Date  Action  Completed 

9.  Date  Returned  to  Request- 
ing Unit 

FS-6600-2  (1/80) 


Figure  3 
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PERIODIC  REVIEW  AND  EVALUATION  REPORT 

Contents 

SECTION 

1 

GENERAL  INFORMATION 

1.1  System  Identification 

1.2  Responsibility 

1.3  Background 

1.3.1  References 

1.3.2  Attachments 

SECTION 

2 

REPORT 

2.1  Overview  of  Review  and  Evaluation 

2.2  Recommendations 

2.3  Review  Procedures 

2.4  Evaluation  Criteria  and  Findings 

Figure  4 

IN-DEPTH  REVIEW  PLAN 
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IN-DEPTH  REVIEW  AND  EVALUATION  REPORT 
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REVIEW  AND  EVALUATION  REPORT 
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MAJOR  EVALUATION  CRITERIA  CATEGORIES 
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II.  OPERATIONAL 
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D.    System  Performance 
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users  at  all  levels. 

2. 

Predetermined  runstreams  used  are 
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A  Proposed  Guideline  for  Documentation  of  Computer 
Programs  and  Automated  Data  Systems  for  the  Operations  Phase 


Thomas  M.  Kurihara,  CDP 

U.S.  Deoartment  of  Transportation 
Office  of  Information  Systems  and  Telecommunications  Policy 


This  paper  presents  a  proposal  for  the  third  publication  of  a  set  of  Federal 
Information  Processing  Standards  (FIPS)  publications  describing  the  documen- 
tation content  guidelines  for  computer  programs  and  automated  data  systems 
for  the  operations  ohase.    The  proposed  guideline  is  necessary  to  complete 
the  work  begun  by  FIPS  Task  Group  14  and  is  in  resoonse  to  the  General 
Accounting  Office  Report  to  the  Congress  of  October  8,  1974,  "Improvement 
Needed  in  Dacumenting  Computer  Systems." 


Keywords:  Documentation,  Federal  Information  Processing  Standards  (FIPS), 
Operations  Phase,  Computer  Programs,  and  Automated  Data  Systems 


1.  INTRODUCTION 


1. 1  Proposal 

This  paper  presents  a  proposal  to  prepare  and  publish  a  guideline  for  documentation  of 
computer  programs  and  automated  data  systems  for  the  operations  phase.    The  purpose  of  the 
guideline  is  to  describe  the  content  guidelines  for  each  document  type  needed  during  the 
operations  phase  of  a  software  life  cycle.    Federal  Information  Processing  Standards(  FIPS) 
Publication  38,  "Guidelines  for  Documentation  of  Computer  Programs  and  Automated  Data 
Systems, "(1)  covers  the  document  types  orepared  during  the  development  phase  o*  a  software 
life  cycle;  and  FIPS  Publication  64,  "Guidelines  for  Documentation  of  Connuter  Programs  and 
Automated  Data  Systems  for  the  Initiation  Phase, "(2)  covers  the  document  tynes  prepared 
during  the  initiation  phase  of  a  software  life  cycle. 


1.2  Need 

The  General  Accounting  Office  (GAO)  in  1971(3)  and  in  1974(4)  cited  the  need  for 
improved  documentation  of  computer  systems.    In  particular,  GAO  cited  increased  costs  of 
operations  and  weakened  management  controls  resulting  from  inadequate  documentation  of 
computer  systems.    The  author  believes  that  the  publication  of  documentation  "ontent 
guidelines  for  the  operations  ohase  will  assist  managers, users ,  auditors,  ana  software 
support  staff  to  establish  and  document  post-implementation  review  functions  and  control 
changes  to  operational  computer  systems. 


1.3  Interest 

In  1977,  the  FIPS  task  Group  14  Chairperson  requested  an  affirmation  of  interest  in 
further  task  force  work  and  recommendations  for  specific  document  types  and  content 
guidelines  from  task  group  members.    The  majority  of  respondents  cited  an  interest  and 
need  for  a  post-implementation  review  document,  project  development  notebook,  and  standards 
and  procedures  manual.    Of  the  document  types  most  frequently  mentioned,  only  the  post- 
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implementation  review  document  is  included  in  this  proposal. 


1.4    FIPS  Task  Group  14  Plans 

The  Chairperson  of  FIPS  Task  Group  14  included  in  the  scope  and  program  of  work  for 
1978  the  development  of  documentation  content  guidelines  for  the  operations  phase.  Because 
of  th    time  required  to  complete  the  work  on  the  draft  FIPS  Publication  64  and  the 
subsequent  disbanding  of  FIPS  task  groups,  no  work  was  started.    The  scope  and  program  of 
work  recommended  were: 


Scope:    To  develop  additional  documentation  content  guidelines  for  documentation  of 
computer  software  during  the  operations  phase.    Include  for  considera- 
tion the  documents  resulting  from  the  user  acceptance  of  comouter  programs 
and  automated  data  systems,  requests  for  changes  to  operational  systems 
and  related  data  bases,  post-implementation  reviews  and  audits,  per- 
formance measurement  and  evaluation,  and  conversion  studies  for  data, 
computer  programs  and  automated  data  systems. 

Program  of  Work: 

t   survey  current  policies  and  practices  of  Federal  executive  agencies 
for  documentation  in  the  operations  phase,  including  the  use  of 
automated  documentation  aids  and  productivity  improvement  tools 

•  assemble  representative  examples  of  documentation  content  guide- 
lines, forms,  and  procedures  that  can  be  used  as  a  starting 
point  for  the  task  group  work 

•  develop  a  FIPS  publication  promulgating  content  guidelines  similar 
to  and  supplementing  FIPS  Publications  38  and  64;  consisting  of 

Part  I     -  Documentation  within  the  Software  Life  Cycle 

Part  II    -  Documentation  Considerations 

Part  III  -  Content  Guidelines  for  Document  Types. 


1.5    Standards  Workshop  Recommendations 

In  the  summer  of  1980,  members  of  the  Washington,  D.C.  metropolitan  area  Federal  ADP 
Users  Group  (FADPUG)  Special  Interest  Group  on  ADP  Standards  and  Quality  Assurance 
(SIGSTD/QA)  organized  a  workshop  to  review  FIPS  Publication  38.    The  result  of  the  workshop 
sessions  was  "A  Proposed  Documentation  Standard  Based  on  a  System  Decomposition  and 
Information  Base  Approach,"  authored  by  Mr.  Saul  Zaveler.(5)    The  workshop  details  were 
reported  in  a  paper  presented  at  the  Software  Engineering  Standards  Applications  Workshop, 
August  18-20,  1981,  in  San  Francisco,  "Observations  on  Documentation  Standards  Revision: 
FIPS  Pub  38  After  Four  Years. "(6)     The  proposed  guidelines  preparation  should  include 
consideration  of  the  recommendations  and  concerns  developed  during  the  SIGSTD/QA  workshop 
on  the  approach  taken  to  prepare  FIPS  Publication  38  and  its  contents  and  structure. 
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2.  RECOMMENDATIONS 


2.1    Document  Content  Guidelines 

The  document  types  included  in  the  guidelines  should  be  a  documentation  record  of 
management,  development  staff,  and  user  activities  during  the  operations  phase,  and  should 
include  the  post-implementation  review  document,  change  control  document,  and  performance 
evaluation  document. 


2.2    Documentation  Standards  Manual 

The  documentation  content  guidelines  issued  by  the  National  Bureau  of  Standards  (NBS) 
as  FIPS  and  those  issued  as  part  of  Reports  on  Computer  Science  and  Technology,  NBS  Special 
publication  500-nn  series  such  as  the  "Computer  Model  Documentation  Guide,"  NBS  Special 
Publication  500-73,(7)  should  be  consolidated  into  a  software  engineering  documentation 
standards  manual . 


3.    Guidelines  for  Documentation  of  Computer  Programs  and 
Automated    Data    Systems    for    the    Operations  Phase 


3.1  Scope 

Computer  programs  and  automated  data  systems  evolve  in  phases,  from  when  an  idea  to 
create  the  software  emerges  through  the  time  that  software  produces  the  required  results. 
Many  different  terms  are  currently  used  to  identify  these  phases  and  the  stages  within  the 
phases.    Three  phases  were  described  in  FIPS  Publication  38--initiation ,  development,  and 
operation.    FIPS  Publication  64  addresses  content  guidelines  for  the  initiation  phase; 
FIPS  Publication  38  addresses  content  guidelines  for  the  development  phase.    The  proposed 
FIPS  publication  addresses  the  operations  phase. 

3.2  Stages  and  Key  Activities 


The  operations  phase  can  be  divided  into  stages,  for  example: 


OPERATIONS  PHASE 

ACCEPTANCE 
STAGE 

OPERATION 
STAGE 

MODIFICATION 
STAGE 

RECERTIFICATION 
STAGE 

TERMINATION 
STAGE 

user  acceptance 
report* 

change  control  d 

post-implementat 
strategic  ADP  pi 

user  acceptance 
report* 

1  1 

performance  measurement  and  evaluation  document — 

1  1 

an  ' 

II                                              1  1 

*part  of  the  post-implementation  review  document 
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3.3    Proposed  Guideline  Contents 

The  proposed  content  guidelines  are  not  intended  to  be  a  complete  set  of  document  types 
which  should  be  determined  by  the  consensus  of  the  working  group.    The  proposed  content 
structure  is  consistent  with  that  of  FIPS  Publications  38  and  64. 

Part  I     -  Documentation  within  the  Software  Life  Cycle 

Part  II    -  Documentation  Considerations 

Part  III  -  Activities  of  the  Operations  Phase 

Part  IV    -  Document  Type  Content 

A.  Post-implementation  Review  Document 

B.  Performance  Measurement  and  Evaluation  Document 

C.  Change  Control  Document 

D.  Strategic  ADP  Plan 
Part  V     -  Glossary 

Part  VI    -  Documentation  and  Review  Methodologies  and  Aids 
4.    POST- IMPLEMENTATION  REVIEW  DOCUMENT 

4.1  Purposes 

The  purposes  of  the  post-implementation  review  are  to  examine  a  delivered  and  accepted 
software  system  and  determine  adequacy  of  the  technical  design,  development  process, 
operational  performance,  cost,  and  user  satisfaction;  to  assess  periodically,  e.g.,  annually, 
its  overall  usefulness;  to  plan  major  modifications;  and  to  plan  for  system  termination. 

4.2  Scope 

The  scope  of  the  review  is  an  assessment  of  the  successes  and  shortcomings  of  project 
performance  and  system  performance.    Users,  software  development  staff,  operations  staff, 
and  auditors  are  involved.    Key  considerations  include  user  acceptance,  system  development 
processes,  lessons  learned,  operating  efficiency,  achievement  of  expected  benefits,  and 
goal  setting  procedures  for  system  expectations. 

4.3  Objective 

The  objective  of  the  post- implementation  review  is  to  determine  whether: 
t    preliminary  studies  were  complete  and  realistic 

•  implementation  progressed  according  to  plan 

•  original  cost/benefit  analysis  projections  were  accurate  and  are 

as  projected 

•  operations,  documentation,  and  system  products  are  adequate 

•  system  performance  and  schedule  expectations  were  realistic  and 
are  being  realized 
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•  changes  and  modifications  were  adequately  handled  and  change 
control  procedures  have  been  implemented 

•  the  system  is  of  value  in  supporting  organizational  mission 
needs. 


4.4    Content  Guidelines 

£ 

The  proposied  content  guidelines  include  those  subject  areas  that  might  be  reviewed  for 
adequacy.  ' 


Section  1.    GENERAL  INFORMATION 
Summary 
Envi  ronment 
References 

Section  2.    MANAGEMENT  SUMMARY 
Requi  rements 
Objectives 

Assumptions  and  Constraints 
Methodology 
Evaluation  Criteria 
Recommendations 

Section  3.    GENERAL  EVALUATION 
User  Acceptance 
Completeness  of  Preliminary 

Studies 
System  Products  and  Data 
Systems  Documentation  and 

User  Procedures 
Security  and  Accountability 
Performance  measurement  and 

Eval uation 
Operations  and  Facilities 
Lessons  Learned 


Section  4.  FEASIBILITY  STUDY  AND  IMPLEMENTATION 
Current  Costs  and  Benefits 
Projected  Costs  and  Benefits 
Explanation  of  Differences 

Section  5.  SYSTEM  DEVELOPMENT  PROCESS 

Description  of  System  Management 

and  Development  Process 
Problems  Encountered  and  Solutions 
Lessons  Learned 

Section  6.  USER  PARTICIPATION  PROCESS 

Description  of  User  Involvement  in 

System  Management  and  Development 

Process 
User  Acceptance  Procedures 
Problems  Encountered  and  Solutions 
Lessons  Learned 


Section  7. 


Section  8. 


STRATEGIC  ADP  PLANNING  PROCESS 
Description  of  Planning  Process  for 

Near-Term  and  Long-Term 
Resource  Requirements 


POST-IMPLEMENTATIO^ 
STEERING  COMMITTEE 


REVIEW  REPORT  TO 


5.    PERFORMANCE  MEASUREMENT  AND  EVALUATION  DOCUMENT 


5.1  Purpose 

The  purpose  of  the  performance  measurement  and  evaluation  is  to  compare  software  system 
performance  measures  and  the  results  of  performance  measurement  and  evaluation  activities 
with  established  criteria  and  expected  results. 

5.2  Scope 

The  scope  of  the  document  covers    the  results  of  planned  and  scheduled  software  system 
performance  evaluations  during  the  operations  phase  using  established  criteria  and  proce- 
dures.   The  results  of  the  evaluation  activities  assist  organizations  in'making  decisions 
during  the  operations  phase  related  to  strategic  planning,  resource  allocation,  utilization, 
system  modifications,  operations,  recertifi cation,  and  termination. 

5.3  Objective 

The  General  Services  Administration  (GSA)  in  November  1978  published  "Management 
Guidance  for  Developing  and  Installing  an  ADP  Performance  Management  Program. "(8)  The 
objective  of  the  GSA  program  is  to  improve  the  effectiveness  of  ADP  systems.    Because  the 
program  is  primarily  oriented  toward  hardware  systems,  additional  management  guidance  is 
needed  for  software  systems. 
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5.4    Content  Guidelines 


The  proposed  content  guidelines  include  those  major  areas  applicable  for  performance 
measurement  and  evaluation. 

Section  1.    GENERAL  INFORMATION  Section  5.    REVISED  EVALUATION  CRITERIA  AND 

MEASURES 

Section  2.    MANAGEMENT  SUMMARY 

Section  6.  RECOMMENDATIONS 

Section  3.    MEASUREMENT  METHODOLOGY 

Appendices  -  Details  of  Performance  Measure- 
Section  4.    EVALUATION  OF  MEASUREMENT  DATA  ments  and  Analysis 

6.    CHANGE  CONTROL  DOCUMENT 

6.1  Purpose 

The  purpose  of  the  change  control  document  is  to  establish  an  orderly,  manageable 
process  for  identifying  changes,  classifying  changes,  evaluating  the  impact  of  changes,  and 
approving  the  changes  to  modify  operational  software  systems. 


6.2  Scope 

The  scope  of  the  document  includes  a  description  of  organization,  activities,  and  pro- 
cedures for  change  control  and  the  documentation  required  to  manage  and  control  changes  to 
software  systems  effectively.    Implementation  of  changes  resulting  from  performance  measure- 
ment and  evaluation  activities  and  conversion  studies  may  be  included  under  change  control 
activities. 


6.3    Content  Guidelines 


The  proposed  content  guidelines  include  those  major  areas  applicable  to  change  control 


Section  1.    GENERAL  INFORMATION 

Section  2.    CHANGE  CONTROL  POLICIES 

Section  3.    APPLICABILITY  AND  IMPLEMENTATION 
POLICIES 

Section  4.    CHANGE  IMPACT  ANALYSIS  METHOD 


Section  5.  CHANGE  CONTROL  DOCUMENTS 
Change  Identification 
Change  Control 
Status  Accounting 

Section  6.  GLOSSARY 

Appendices    -  Change  Control  Organization, 
Procedures  and  Forms 


6.4    Related  Standardization  Activities 


The  Electronics  Industries  Association  and  the  Institute  of  Electrical  and  Electronic 
Engineers  are  involved  in  standardization  acitivies  for  data  management  and  configuration 
management  in  Department  of  Defense  contracting  activities. 

7.    STRATEGIC  ADP  PLAN 
SYSTEMS 


7.1  Purpose 

The  purpose  of  the  plan  is  to  document  the  strategic  automatic  data  processing  planning 
activities  which  coordinate  systems  planning,  systems  development,  systems  acquisition,  and 
system  operations.    The  activities  and  resulting  plan  show  what  operational  and  planned 
software  systems  support  mission  needs  and  how  available  and  expected  resources  are  alloca- 
ted in  the  time  period  covered  by  the  plan. 
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7.2  Scope 


The  scope  of  the  ADP  plan  includes  the  software  and  hardware  systems  needed  to  run  the 
software,  people,  dollars,  and  facilities  needed  to  plan,  develop,  acquire,  manage,  and  use 
computer-based  information  systems.    The  plan  should  include  information  resulting  from 
planning  activities  at  each  organizational  level. 

7.3    Content  Guidelines 

The  proposed  content  guidelines  include  those  major  areas  applicable  to  strategic 


planning. 

Section 

1. 

GENERAL  INFORMATION 

Section  7. 

CONCEPT  OF  OPERATIONS 

Development 

Section 

2. 

MANAGEMENT  SUMMARY 

Acquisition 

Systems  Operation  and  Management 

Section 

3. 

PLANNING  POLICIES 

User  Involvement 

Section 

4. 

PLANNING  METHODOLOGY 

Section  8. 

ALLOCATION  OF  RESOURCES 

Section 

5. 

ORGANIZATION  MISSION  NEEDS 

Appendices 

-  Details    of  Studies,  Analysis, 

and  Resource  Allocation 

Section 

6. 

TECHNOLOGY  ASSESSMENT 

8.  CONCLUSION 


Well  written  documentation  does  more  than  describe  the  programming  language  code.  It 
communicates  information  about: 

t    intended  purpose  and  use  of  software  systems 

•  transformation  of  requirements  into  a  design  for  development  of 
a  software  system 

•  development  process 

•  performance  criteria  and  expected  changes 

t  controls  for  data  and  for  operation  of  the  software  system 

t  limitations,  constraints  and  assumptions 

•  user  acceptance  criteria  and  acceptance  procedures 

•  operation  for  auditing  and  verification  of  software  systems. 


FIPS  Publications  64  and  38  describe  the  document  content  guidelines  for  the  initiation 
and  development  phases.  Another  FIPS  publication  is  needed  to  communicate  information  about 
the  activities  related  to  the  operations  phase. 

A  final  note:    Documentation  standards  and  guidelines  should  be  developed  after  the 
management,  technical,  and  user  activities  are  described.    Once  these  activities  are 
described  and  are  accepted  as  good,  uniform  practices  to  be  followed  for  developing 
reliable,  hi qh-quality software,  the  documentation  content  guidelines  will  become  more  useful 
as  an  aid  for  effective  communications.    With  the  FIPS  for  the  management,  technical  and 
user  practices,  documentation  standards  and  guidelines  will  be  more  valuable  to  the  Federal 
community.    Since  there  appears  to  be  very  little  emphasis  on  defining  uniform  practices  in 
software  development,  the  development  of  software  documentation  content  guidelines  is  needed 
to  encourage  better  communication  about  software  systems  during  the  operations  phase. 
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NBS  FIPS  Software  Documentation  Workshop,  March  3,  1982 


Session  B:    Documentation  for  Operation  and  Maintenance 
Synopsis  of  Discussion 

Nancy  Mae  Bonney  ' 
Dynamac  Corporation 
The  following  comments  were  made  by  audience  participants: 

We  only  need  general  guidelines,  like  a  checklist  of  items  that  system  developers 
should  not  overlook.    Because  of  the  rapidly  changing  ADP  environment  (e.g.,  personal 
computers,  user-oriented  languages,  etc.),  specific  standards  for  on-line  user-driven 
systems  might  be  obsolete  before  they  were  published.    Perhaps  the  situation  has  to 
'crystallize'  for  a  while  longer.  --  Carol  Uri,  Federal  Communications  Commission. 

Most  of  the  comments  and  presentations  were  geared  to  business  systems  or  on-line 
business  applications.    There  is  a  great  need  for  software  documentation  and 
maintenance  procedures  for  on-line  machine  control,  distributed  process  control  and 
interactive  systems.  --  John  Maupe,  U.S.  Postal  Service. 

Research  is  needed  in  presentation  syle  and  in  writing  style.    The  results  should  be 
applied  as  an  addendum  to  each  documentation  content  guideline  issued  in  the  FIPS 
program.    Writing  style  and  presentation  must  consider  management  needs,  audience, 
document  type,  and  application.    We  need  more  than  the  GPO  Style  Manual .    Tom  Kurihara, 
U.S.  Department  of  Transportation 

I  still  fail  to  comprehend  how  a  single  universal  standard  can  be  all  things  to  all 
people.    It  would  seem  that  documentation  content  guidelines  must  be  developed  in-house 
for  a  specific  group  of  users.    Standards  are  of  course  necessary,  but  must  be 
developed  toward  unique  environments.  —  Anonymous 

FIPS  PUB  38  guidelines  for  the  Users  Manual,  Operation  Manual,  and  Program  Maintenance 
Manual  should  provide  a  recommended  documentation  structure  and  content  that  allow  for 
the  manuals  to  be  easily  maintained  over  the  system's  lifetime.  Currently,  amendments 
to  the  users  manual  turn  out  to  be  quite  large  because  of  the  documentation  structure. 
Also,  the  user  community  now  needs  different  types  of  manuals:  a  management  type,  a 
terminal  instructions  type,  and  in  some  cases,  a  distributed  processing  type  for  field 
users.  --  Carolyn  Cowden,  Calculon  Corporation 

Documentation  should  be  targeted  to  'user  levels'  in  the  next  publication  of  the  FIPS 
documentation  standards.  --  Charles  R.  Cooke,  U.S.  Department  of  Health  and  Human 
Services 

We  need  to  distinguish  between  system  management  (operation  phase)  and  project 
management  (development  phase).    These  are  quite  different.    We  need  to  maintain  the 
documents  produced  in  the  development  phase  in  the  operation  phase  (e.g.,  the 
Operations  Users  Manual,  and  Maintenance  Manual).    We  need  to  have  in-code  (in  program) 
documentation  developed  during  the  development  phase  and  updated  during  the  operation 
phase.    Program  technical  documentation  is  more  beneficial  (maintainable)  when  in 
actual  program  code.    —  Michael  A.  Regardie,  U.S.  Navy  Recuriting  Command 
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We  should  follow  all  the  recommendations  presented,  and  be  aware  of: 

1)  On-line  vs.  batch  (environments). 

2)  Computer  operator  vs.  the  terminal  operator  as  users. 

3)  User  operation  must  be  broken  down  also  into;  a)    clerical,  b)  data  entry,  c) 
management,  d)    other.  —  F.  Colison,  Defense  Logistics  Agency 

I  definitely  recommend  a  separate  guideline  for  the  operation  phase.    Such  a  document 
should  address  the  areas  of: 

a)  Change/modification  process  (software). 

b)  Ongoing  life  of  User  and  Operations  guides. 

c)  Multiple  user  audiences. 

Basically,  I  recommend  something  similar  to  the  content  guidelines  proposed  by  T.  M. 
Kurihara.    —  Rod  Smart,  U.S.  Department  of  the  Interior 

I  agree  with  Mr.  Kurihara's  recommendations  to  address  different  modes  of  operation  and 
different  audiences  but  in  a  combined  publication  of  FIPS  PUBS  30,  38,  and  64.  The 
addition  of  hardware  configuration  and  error  message  documentation  in  the  revision 
would  be  very  helpful  also.  —  Bonita  Condon,  National  Institutes  of  Health 

FIPS  PUB  38  should  be  expanded  to  cover  the  operation  phase,  but  I  would  stress  the 
idea  of  using  it  as  a  guide.    The  audience  must  be  the  primary  consideration.  Cathy 
Mason,  Calculon  Corporation 

Other  points  were  made  during  the  session  discussions,  including: 

-  Will  management  support  quality  documentation  considering  its  potential  cost? 

-  Following  FIPS  PUB  38  as  a  rule  will  not  result  in  quality  documentation. 

-  From  the  users'  standpoint,  the  documentation  is  either  usable  or  not;  whether  it 
meets  FIPS  guidelines  is  a  different  issue. 

-  Documentation  as  well  as  programs  must  be  tested;  this  is  one  way  to  determine 
the  quality  of  documentation. 

-  Will  change  control  work  in  urgent  situations?    If  standard  change  control  is 
bypassed  in  urgent  situations,  how  does  one  make  sure  the  appropriate  procedures 
are  followed  after  the  fact? 

-  Standards  have  frequently  been  developed  so  that  they  are  easy  to  implement  and 
maintain,  rather  than  useful  to  the  user  audiences. 

-  Each  government  agency  should  develop  their  own  standards  based  on  FIPS 
documentation  guidelines;  telling  a  contractor  to  "use  FIPS  PUB  38"  does  not 
provide  enough  guidance. 

-  The  FIPS  documentation  publications  are  guidelines  only,  and  are  not  a  substitute 
for  good  management  decisions  about  system  documentation. 
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The  conclusions  of  the  session  indicated: 

-  the  necessity  for  management  and  personal  commitment  for  quality  documentation, 

-  the  FIPS  PUBS  are  content  guidelines,  not  standards, 

-  we  must  write  to  the  audience, 

-  the  coverage  of  the  existing  FIPS  documentation  guidelines  needs  to  be  broadened, 
and 

-  a  revision  and  combination  of  FIPS  PUBS  64  and  38,  to  include  documentation 
guidelines  for  the  operation  phase,  would  be  useful  and  appropriate. 
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SESSION  C:    Tools  for  Improved  Documentation 

Introduction 

Moderator:    Raymond  C.  Houghton,  Jr. 

Institute  for  Computer  Sciences  and  Technology 
National  Bureau  of  Standards 


In  this  session,  there  is  a  discussion  of  a  good  cross  section  of  the  types  and 
applications  of  documentation  tools.    It  includes  tools  that  are  currently  available  for 
application.    It  includes  tools  which  address  documentation  issues  for  specific  phases 
of  the  life  cycle  or  for  multi-phases  of  the  life  cycle.    More  important,  the  tools 
discussed  cover  the  entire  life  cycle  from  requirements  specification  to  code 
maintenance. 

The  first  paper  by  S.  Lee  Henry  provides  a  good  introduction  to  the  issues 
associated  with  the  effects  of  technology  on  documentation  and  more  important,  on 
documentation  standards.    This  discussion  leads  nicely  into  the  specific  tool  coverage 
of  the  next  four  papers. 

A.  Malhotra  (et.  al.)  brings  back  a  familiar  phrase  that  was  once  assigned  to 
COBOL,  that  of  "executable  documentation".    This  paper,  however,  discusses  a  language 
that  allows  its  user  to  work  at  a  much  higher  level  of  abstraction.    This  higher  level 
does  bring  us  closer  to  the  problem  domain  and  consequently  may  actually  bring  us  closer 
to  "executable  documentation". 

T.  C.  Ting  shows  us  that  documentation  can  also  be  a  subject  of  academic  interest. 
He  discusses  a  tool  currently  under  development  at  the  Worcester  Polytechnic  Institute 
that  integrates  documentation  development  into  the  earlier  phases  of  software 
development. 

Bruce  Blum  shows  us  how  a  system  can  maintain  documentation  throughout  the  life 
cycle.  His  system  has  the  advantage  of  addressing  a  very  specific  application  area, 
thus  making  it  possible  to  automate  much  of  the  development  and  maintenance  process. 

Finally,  Linda  Lawrie  discusses  a  "real  world"  tool  that  generates  documentation 
from  user-embedded  conmients  and  the  code  itself.    An  important  issue  that  she  brings  out 
in  her  paper  and  that  brings  us  back  to  the  theme  of  the  conference  is  that 
documentation  standards  can  be  cumbersome  when  they  are  applied  to  documentation 
systems.    It  is  important  for  documentation  standards  to  be  flexible  so  that  they  do  not 
stifle  technological  progress. 
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State-of-the-Art  Documentation 
What  is  it? 
How  does  it  Affect  Documentation  Standards? 


S,  Lee  Henry 


American  Management  Systems,  Inc. 


"State-of-the-art",  when  applied  to  documentation,  describes  a  process  as 
well  as  a  product.  State-of-the-art  documentation  is  accurate,  usable  and  easy  to 
update.  It  conserves  effort  in  the  design,  programming  and  maintenance  of 
computer  systems.  This  paper  discusses  the  effects  of  software  technology  on 
current  documentation  format  and  content  standards  and  suggests  procedural 
guidelines  which  aid  in  the  preparation  and  maintenance  of  state-of-the-art 
documentation . 


Keywords:    Procedures;    Guidelines;    Software;  Compatibility 


1.  INTRODUCTION 


Software  documentation  is  written  to  protect  the  investment  made  by  system  designers 
and  programmers.  Anyone  who  weighs  the  cost  of  documentation  against  the  savings  it 
produces  in  system  modification  and  user  training,  recognizes  that  documentation  is  an 
integral  part  of  software  development.  In  addition,  state-of-the-art  documentation  makes  it 
possible  to  better  centralize  development  efforts,  reduce  programmers'  workload,  facilitate 
testing  and  maintain  a  clearing  house  of  current  information  during  system  development  and 
maintenance.  The  state-of-the-art  of  documentation  has,  therefore,  come  to  have  several 
important  requisites. 

One  is  that  it  must  be  cost-effective  to  produce.  The  cost  of  documentation  should  be 
proportional  to  the  cost  of  programming.  It  is  not  unusual  for  the  amount  and  type  of 
documentation  to  be  included  in  software  contracts.  This  places  a  very  real  limit  on  what 
can  be  spent  producing  it. 

Another  is  that  it  must  be  accurate.  Good  documentation  can  give  a  good  system  the 
competitive  edge  it  needs  in  the  software  marketplace.  In  addition,  with  the  rapid  turnover 
in  data  processing  personnel,  documentation  often  is  relied  upon  to  transmit  information 
from  one  employee  "generation"  to  the  next. 

Lastly,  and  never  leastly,  it  must  be  usable.  Information  must  be  in  a  format  such 
that  it  is  easy  to  find  and  readable.  Principles  of  human  engineering  applied  to 
documentation  suggest  that  document  formats  be  standardized,  levels  of  detail  be  closely 
matched  to  the  need  of  the  intended  audience  and  figures  and  charts  be  used  profusely. 
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2.    CURRENT  TOOLS 


Current  software  tools  make  it  possible  to  adhere  to  format  standards  and  increase  the 
cost-effectiveness,  accuracy,  and  usability  of  documents.  The  technology  itself  offers  a 
great  deal  of  compatibility  with  current  FIPS  guidelines  for  document  format  and  content. 
Although  differences  between  the  tools  may  dictate  some  elements  of  format,  each  offers 
extremely  important  advantages. 

Word  processors  allow  straight-forward  control  over  the  format  of  documents  through  the 
"what  you  see  is  what  you  get"  approach.  Setting  up  page  formats,  tabs,  margins,  etc.  is 
visually  re-inforced  as  the  text  image  is  transformed  on  the  screen. 

Text  editors,  on  the  other  hand,  take  the  "set  it  up  and  run  it  through"  approach.  The 
formatting  commands  are  imbedded  throughout  the  text,  and  the  resultant  text  is  available 
after  processing.  Most  text  processors  automatically  number  sections  as  well.  Some  can 
create  tables  of  contents  and  indexes. 

What  all  text  and  word  processors  have  in  common,  of  course,  is  the  obvious  advantage 
of  being    able  to  modify  a  document  without  the  need  for  messy  or  tedious  manual  correction. 

It  is  sometimes  possible  to  interface  these  tools  with  sophisticated  output  devices  -- 
such  as  laser  printers  and  phototypesetti ng  equipment  --  enhancing  the  attractiveness  of 
documents  at  reasonable  cost. 

Automatic  documentation  programs,  on  the  other  hand,  are  an  entirely  different  kind  of 
tool.  They  use  the  software  itself  as  input  and  vary  greatly  in  the  kind  and  amount  of  data 
they  produce.  Some  supply  information  on  the  files  used  by  the  software  while  others  draw 
flowcharts.  By  extracting  information  from  the  program  being  documented,  they  help  to 
ensure  the  utility  of  the  resultant  documentation. 

The  use  of  word  processors,  text  processors,  automatic  documentation  tools  and 
computer-controlled  output  devices  requires  technical  competence  with  text  processors  and 
file  handling  utilities  as  well.  In  order  to  reduce  the  complexities  and  cost  of  developing 
standard  documentation  and  extracting  information  from  the  software,  standard  procedures 
should  be  developed  that  are  commensurate  with  standards  applied  to  the  development  of 
software . 


3.    SUGGESTED  PROCEDURAL  STANDARDS 


3.1    Notation  Conventions 

Notation  conventions  add  clarity  to  software  documentation.  Whether  one  is  marking  the 
difference  between  user-entered  and  system-generated  data  on  a  terminal,  or  noting  required 
and  optional  parts  of  syntax,  notation  conventions  convey  a  lot  of  information  to  a  user  in 
a  brief  format. 

Current  tools  provide  several  means  with  which  notation  conventions  can  be  expressed. 
Upper  and  lower  case  conventions  can  be  maintained,  bold-face  and  regular  type  can  often  be 
used,  or  the  absence  and  presence  of  underlining  can  make  the  distinction. 

Whatever  convention  is  decided  upon  should  be  used  consistently  and  should  be  one  that 
can  be  expressed  within  the  document  file  itself,  rather  than  one  which  requires  manual 
"fixes"  later.  The  advantage  that  text  and  word  processors  have  over  manual  methods  of 
documentation  production  is  that  commands  which  "carry"  the  information  concerning  the 
upper/lowercase,  type-face  or  underlining  convention  can  be  part  of  the  document  file.  This 
makes  it  possible  to  modify  the  documentation  without  having  to  rethink  the  examples  or 
syntax  descriptions. 
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3.2  Inclusion  of  Working  Examples 

Another  of  the  benefits  of  software-based  documentation  is  that  it  permits  the  user  to 
imbed  tested  examples  (commands,  inquiries,  command  files,  JCL,  etc.)  into  documentation 
without  having  to  enter  them  manually.  This  saves  a  lot  of  effort,  especially  if  it  only 
takes  a  single  command  to  pull  the  example  into  the  text  of  the  document.  It  also 
guarantees  the  accuracy  of  the  document.  Little  is  more  discouraging  to  a  new  user  than  to 
try  an  example  from  the  document  and  find  out  it  doesn't  work. 

3.3  Standard  Sections 

Just  as  examples  can  be  inserted  into  a  document  file,  standard  sections,  such  as 
notation  conventions,  terminology,  or  system  overviews,  can  be  prepared  separately  and 
imbedded  in  any  document  which  requires  them. 

Standard  sections  strengthen  the  apparent  relationship  between  documents  in  a  "package" 
and  make  each  of  the  documents  more  self-contained. 

3.4  Software  and  Documentation  Update  Procedures 

Updates  to  existing  documents  should  also  follow  standardized  procedures.  One  of  the 
first  and  most  important  of  these  is  a  wel 1 -publ ici zed  cycle  for  documentation  updates, 
coordinated  with  software  releases  or  some  annual  period. 

Standard  procedures  for  filing  and  fixing  "bugs"  in  both  the  software  and  the 
documentation  can  be  used  to  simplify  and  control  the  process  of  modification.  Problems 
should  be  submitted  on  standard  forms  which  make  it  easy  for  a  user  to  clearly  identify  the 
problem  he  is  having.  He  should  know  what  kind  of  data  to  submit  with  the  form,  know  where 
to  send  it,  and  expect  to  get  feed-back  from  someone  responsible  for  program  maintenance. 
One  procedure  for  using  current  tools  for  this  update  cycle  is  to  set  up  a  special  data  base 
for  "action  items".  This  allows  the  problem  spots  to  be  randomly  surveyed.  Specific 
problems  an  be  routed  to  those  responsible  for  fixing  the  software  or  modifying  the 
documentation.  Reports  can  be  routinely  distributed  to  inform  everyone  involved  of  the 
current  status  of  the  software.  Further,  action  items  can  be  prioritized  to  add  managament 
control  over  the  modification  of  both  software  and  documentation.  When  problems  are  fixed, 
a  copy  of  the  original  form  can  be  returned  to  the  person  v/ho  sent  it  in.  This  encourages 
those  who  give  the  system  its  most  thorough  test  to  keep  the  development  and  maintenance 
groups  informed  of  its  performance. 

3.5  Back-up  and  Archival  Storage  of  Documents 

The  use  of  text  processors  also  requires  development  of  standard  procedures  for  back-up 
and  archival  of  document  files.  A  system  crash  or  user  error  cannot  be  allowed  to  destroy 
weeks  of  work.  Documents  can  be  backed  up  to  tape,  disk  or  diskette  depending  on  the  system 
being  used.    Documents  can  then  be  restored  from  backup  copies  if  current  files  are  damaged. 

OCR  scanning  further  permits  documents  which  are  printed  in  OCR  type-face  to  be 
re-entered  from  hard-copy. 

3.6  Documentation  Specialists  and  the  Software  Team 

State-of-the-art  documentation  involves  a  coordination  of  programmers  and  writers  in  a 
"team"  effort.  Techniques  used  in  the  devel  opnlent ,  testing,  and  maintenance  of  software 
often  parallel  those  used  in  development,  testing,  and  maintenance  of  documentation.  The 
documentation  specialist  should,  therefore,  be  a  member  of  the  software  development  team, 
familiar  with  the  tools  at  his  disposal. 

In  addition,  the  more  familiar  he  is  with  the  software,  the  more  likely  he  will  be  able 
to  serve  as  a  source  of  current  information  during  planning  and  development.  Documentation 
that  is  produced  during  development  can  serve  as  an  important  means  of  information  transfer 
and  a  way  of  reliably  capturing  decisions  which  are  made  as  well  as  those  that  still  need  to 
be  made. 
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3.7  Internal  Documentation  During  System  Development 

Programmers,  at  the  same  time,  should  always  be  required  to  document  their  work. 
Flowcharts,  logic  diagrams  and  tables  should  be  produced  whenever  possible.  These  shortened 
versions  of  system  information  can  be  re-used  as  figures  or  appendices  in  the  final 
documentation  when  appropriate. 

Throughout  system  development,  the  growing  body  of  documentation  should  be  available  to 
documentation  specialists,  programmers  and  management.  It  can  be  used  to  monitor  progress 
and  review  development  goals. 

3.8  Testing  the  Documentation 

Another  important  advantage  of  the  sophisticated  documentation  specialist  and  his  role 
in  the  software  development  team  is  that  he  can  "test"  the  documentation  by  applying  what  is 
written.  This,  of  course,  provides  a  further  test  of  the  system  too.  It  helps  to  ensure 
the  integrity  of  the  document  and  guarantees  that  the  writer  has  the  proper  "slant"  on  the 
system. 


4.  CONCLUSION 


The  software-based  production  of    documentation    can    greatly    improve    its  accuracy, 

maintainability,  and,    often,    its  attractiveness  --  so  much  so  that  it  is  becoming  more  the 

rule  than    the    exception    in    the  software    industry.      Production     of  state-of-the-art 

documentation,  however,    requires  additional    control    over  costs  and  production  procedures 

which  parallel  that  applied  to  the  development  of  software. 
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ABSTRACT:  EAS-E  is  a  programming  language  integrated  with  a  database  management  system  that  is 
under  development  at  the  IBM  Thomas  J.  Watson  Research  Center.  This  paper  discusses  the  EAS-E 
approach  to  program  documentation.  EAS-E  programs  consist  of  high-level  operations  on  entities, 
attributes  and  sets.  The  syntax  has  been  designed  to  be  compact  and  readable.  This  paper  compares 
EAS-E  programs  to  programs  in  PL/I-DL/I  and  PL/I-SQL  and  shows  that  EAS-E  programs  are 
shorter  and  have  much  less  non-problem-related  code.  Thus,  they  can  be  viewed  as  "executable 
documentation". 


Keywords:  English-Like,  Self  Documenting,  Programming  Language 


1.  INTRODUCTION 


EAS-E  (pronounced  EASY)  is  an  interactive  programming  language  integrated  with  a  database  management  system 
that  is  under  development  for  VM/370  at  the  IBM  Thomas  J.  Watson  Research  Center.  EAS-E  provides  a  full-screen 
input/output  facility  through  an  interface  with  DMS/CMS  (6),  a  non-procedural  facility  for  "browsing"  the  database 
(12),  and  a  report  generator.  The  EAS-E  database  management  system  (9)  is  capable  of  efficiently  supporting  very 
large  databases  stored  on  multiple  DASD  extents.  It  supports  locking,  detects  deadlocks  and  protects  the  integrity  of 
the  database  against  hardware  and  software  crashes.  In  this  paper  we  shall  only  concern  ourselves  with  the  features 
that  make  EAS-E  programs  compact  and  readable.  These  are  discussed  below: 

A.  The  Entity,  Attribute  and  Set  (EAS)  Model.  The  application  or  system  to  be  implemented  is  analyzed  in  terms  of  the 
Entities,  Attributes  and  Sets  that  determine  its  status  at  a  given  point  in  time.  In  section  3.2  we  show  that  a  wide 
variety  of  data  structures  are  either  special  kinds  of  sets  or  are  almost  immediately  expressible  as  EAS  structures.  The 
simplicity  of  the  basic  concepts  makes  it  possible  to  document  the  EAS  status  of  a  system  or  appUcation  in  a  simple 
manner. 

Programs  generate  and  maintain  this  status.  They  consist  of  higher-level  operations  on  entities,  attributes  and  sets. 
Since  the  statements  of  the  program  relate  directly  to  the  concepts  used  in  analyzing  the  application  or  system,  their 
intentions  are  usually  quite  clear. 

B.  Powerful  Integrated  Commands.  The  program  statements  operate  on  entities,  attributes  and  sets.  For  example,  they 
may  create  an  entity,  assign  values  to  its  attributes,  file  it  into  a  set,  and  later  find  it  on  the  basis  of  these  attributes. 
These  high  level  commands  are  translated  by  the  EAS-E  software  into  lower  level  operations  that  communicate  with 
the  database  manager,  search  and  maintain  set  structures,  etc.  Thus,  the  programmer  works  in  terms  of  higher  level 
concepts  and  need  not  be  concerned  with  low  level  details  like  the  management  of  pointers  in  data  structures.  EAS-E 
is  an  integrated  language  in  that  the  programmer  refers  to  entities  in  main  storage  and  in  the  database  in  exactly  the 
same  manner.  This  simplifies  programming  and  also  makes  programs  more  compact. 

C.  English-Like  Syntax.  The  commands  that  specify  the  operations  on  entities,  attributes  and  sets  are  written  as 
English-like  sentences.  This  makes  them  easy  to  read  and  understand  by  non-programmers  as  well  as  programmers. 
We  shall  show  that,  despite  EAS-E's  English-like  syntax,  EAS-E  programs  are  more  compact  than  equivalent 
programs  in  other  languages. 

It  has  become  clear  that  program  documentation  that  is  produced  separate  from  and  in  addition  to  the  executable  code 
does  not  work.  It  does  not  get  updated  when  the  code  is  updated,  particularly  under  time  pressure,  and  is  usually  out 
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of  date  and  misleading.  We  believe  that  the  compact,  English-like  EAS-E  programs  are  self-documenting  and  obviate 
the  need  for  program  documentation. 

Section  2  discusses  the  HAS  model  and  a  simple  method  of  documenting  EAS  structures.  Section  3  discusses  some 
features  of  the  EAS-E  language.  Section  4,  on  Integrated  Language,  compares  EAS-E  with  two  leading  database 
languages.  In  these  comparisons  we  are  primarily  interested  in  the  size  and  the  understandability  of  the  source  code. 
We  shall  show  that  the  EAS-E  programs  are  compact  because  several  functions  are  taken  care  of  by  system  software 
instead  of  being  coded  by  the  programmer. 


2.  THE  EAS  MODEL 


Webster's  Unabridged  Dictionary  (second  edition)  defines  an  entity  as  "that  which  has  reality  and  distinctness  of 
being  either  in  fact  or  for  thought  ..."  In  an  EAS-E  representation,  it  is  usually  some  "thing"  (account,  check,  job)  of 
the  real  world  to  be  represented  in  the  database.  The  attributes  of  an  entity  can  be  considered  to  be  its  properties  or 
characteristics.  At  any  instant  in  time  an  attribute  has  at  most  one  value  or  it  may  be  undefined. 

In  EAS-E,  as  in  SIMSCRIPT  (7)  and  DBTG  (3)  ,  a  set  is  an  ordered  collection  of  zero,  one,  or  more  entities  which  is 
owned  by  some  entity.  To  illustrate:  each  account  owns  a  set  of  current  transactions,  i.e.,  checks  and  deposits  which 
have  occurred  since  the  last  monthly  statement.  Thus,  the  account  for  John  Smith  owns  one  such  set,  that  for  Mary 
Jones  owns  another  such  set,  etc.  In  general,  we  say  that  each  account  owns  its  current  transaction  set.  Accounts  may 
also  own  a  set  of  old  transactions,  outstanding  loans,  etc. 

An  entity  may  have  any  number  of  attributes,  own  any  number  of  sets  and  belong  to  any  number  of  sets.  An  entity 
can  both  own  a  set  of  a  given  name  and  belong  to  a  set  with  the  same  name.  These  general  facilities  allow  more 
specialized  structures,  such  as  trees  and  networks,  to  be  expressed  more  or  less  trivially  within  the  general  framework 
of  entities,  attributes  and  sets.  This  is  discussed  in  section  3.2.  A  more  detailed  discussion  of  the  power  of  the  EAS 
formalism  can  be  found  in  (11). 

During  the  systems  analysis  phase  the  design  team  should  decide  on  the  Entities,  Attributes,  and  Sets  that  are  needed 
to  describe  the  status  of  the  system.  These  should  be  documented,  preferably  in  the  manner  shown  below.  Once  this 
is  done,  event  programs  can  be  designed  to  alter  the  EAS  status  as  necessary^. 

Exhibit  1  documents  the  EAS  structure  of  a  system  that  keeps  track  of  JOBs  of  different  types.  JOBs  consist  of 
TASKs  which,  in  turn,  may  be  made  up  of  SUBTASKS.  The  responsibility  for  these  JOBs  is  delegated  to  GROUPs 
which  are  subdivided  into  AREAs. 

The  EAS  structure  is  documented  in  a  columnar  fashion.  The  first  column  contains  the  names  of  the  entity  types  in 
the  system.  Each  entity  type  is  followed  by  a  list  of  its  attributes  in  column  two.  Columns  three  and  four  contain  the 
names  of  the  sets  the  entity  type  owns  and  belongs  to  respectively.  To  the  right  of  column  four  is  a  space  for 
comments. 

The  format  of  exhibit  1  is  recommended  for  documenting  database  and  main  storage  EAS  structures  but  the  structures 
have  to  be  defined  by  translating  this  information  into  English-like  definitions.  We  are,  however,  working  on  a  facility 
that  will  allow  the  user  to  define  EAS  structures  directly  with  a  format  similar  to  this. 


3.  THE  EAS-E  PROGRAMMING  LANGUAGE 


Since  the  status  of  an  application  or  a  system  is  described  completely  in  terms  of  the  entities,  attributes,  and  sets  in 
existence  at  any  point  in  time,  events  can  change  status  in  only  a  limited  number  of  ways.  They  can: 

•  Create  or  destroy  entities. 

•  Assign  or  change  attribute  values. 

•  File  or  remove  entities  from  sets. 

Commands  for  the  above  actions  have  an  English-like  syntax.  For  example: 

CREATE  A  TASK 

DESTROY  THE  TASK  CALLED  T2 

LET  PRIORITY(TASK)  =  5 

FILE  THIS  TASK  IN  JOB.TASKS 

REMOVE  THE  FIRST  TASK  FROM  JOBS.TASKS 


+  The  acronym  EAS-E  comes  from  Entities,  Attributes,  Sets  and  Events 
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Entity 
JOB 


Attribute 


Owns 


Belongs 


TASK 


JOB_NUMBER 

JOB_CUSTOMER_NAME 

JOB_DESCRIPTION 

JOB  TASKS 


TASK_AREA_NUMBER 
TASK_DESCRIPTION 
TASK_JOB_NUMBER 
SUBTASK  OWNER 


SUBTASKS 


SUBTASKS 
JOB_TASKS 
AREA  TASKS 


Comment 


Text  variable 
Text  variable 
Text  variable 
Tasks  of  the  job 


Alpha  variable 
Text  variable 
Text  variable 
Identifier  variable 
Tasks  can  both  own 
and  belong  to  subtasks 


AREA 


GROUP 


AREA_NAME 
AREA_NUMBER 
AREA  TYPE 


GROUP_NAME 
GROUP  NUMBER 


AREA  TASKS 


GROUP  AREAS 


GROUP  AREAS 


Text  variable 
Alpha  variable 
Integer  variable 
Tasks  of  the  area 


Text  variable 
Alpha  variable 
Areas  of  the  group 


Exhibit  1  :  An  Example  EAS  Structure 

Thus,  EAS-E  programs,  which  are  collections  of  such  commands,  can  be  read  like  English  prose.  Note  that  the 
commands  must  conform  to  a  predefined  syntax,  they  cannot  be  written  in  free  English,  but  the  syntax  has  been 
designed  to  make  their  intentions  clear  and  unambiguous. 

We  will  illustrate  features  of  the  EAS-E  language  by  examples'''  from  the  first  application  system  developed  using 
EAS-E:  a  rewrite  and  extension  of  the  Workload  Information  System  of  Thomas  J.  Watson's  Central  Scientific 
Services  (CSS).  CSS  consists  of  about  100  craftsmen  who  do  model  shop,  glass  work,  electronics,  etc.,  for  Thomas.  J. 
Watson's  scientists  and  engineers.  The  old  Workload  Information  System,  written  in  PL/I  and  assembler,  was  difficult 
to  modify  or  extend.  The  EAS-E  version  duplicated  the  function  of  the  old  system:  it  read  the  same  weekly  inputs 
and  generated  the  same  outputs.  It  achieved  this  with  about  one-fifth  as  much  source  code  as  the  old  system.  It  also 
showed  an  even  greater,  but  difficult  to  quantify,  advantage  over  the  old  system  in  terms  of  ease  of  modification  and 
extension.  The  system  has  now  been  extended  to  accept  certain  inputs  and  provide  certain  outputs  on-line  rather  than 
batch. 

3.1  Understandable  Syntax 

Exhibit  2  is  a  routine  from  the  CSS  system  whose  function  is,  as  it  says,  to  start  a  new  page  and  print  a  heading.  This 
routine  is  called  in  the  printing  of  several  different  reports.  The  START  NEW  PAGE  statement  is  self-explanatory. 
The  seven  lines  (including  the  blank  seventh  line)  following  the  PRINT  7  LINES...  statement  are  printed  during 
run-time  just  as  they  appear  in  the  source  program,  except  that  the  first  variable,  PAGE.'V  (automatically  maintained 
by  EAS-E)  is  printed  in  place  of  the  first  grouping  of  ***s,  the  second  variable  TITLE  is  printed  in  place  of  the 
second  groupings  of  *s,  etc.  Though  the  routine  is  without  comment,  its  action  should  be  clear  to  anyone. 

The  PRINT  statement  in  exhibit  3,  slightly  simplified  from  its  CSS  version,  prints  3  lines  containing  the  specified 
variables  and  expressions  in  the  places  indicated  in  the  three  form  lines  (last  3  lines  of  the  exhibit).  These  lines  will 
print  data  under  the  headings  of  exhibit  3. 

The  example  of  a  FIND  statement  reproduced  in  exhibit  4,  including  the  IF  ONE  IS  (NOT)  FOUND  statement  that 
usually  follows  a  FIND,  finds  the  job  in  CSS  JOBS  with  the  specified  job  number.    In  fact,  the  FIND  statement 


The  complete  syntax  is  available  in  (8). 
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Exhibit  2: 

ROUTINE  TO  START_NEW_PAGE_AND_PRINT_HEADING 
START  NEW  PAGE 

PRINT  7  LINES  WITH  PAGE  .  V ,  TITLE ,  SUBTITLE ,  DATE ,  AND  WEEK  THUS  .  .  . 
CSS  Information  System  Page  *** 

Central  Scientific  Services 

:|c  :|c  :|c  :|c  :|c  :|c  :|c  :|c  3|c  :ic  3|c  *  *  *  4:  :|c  3|c  !|:  Ik  :ic  :|c  *  >|c  >|c  9|t  *  I):  *  ^  ^  1c  )|c  :(c  :(c  i|c  :tc  ^  :|c  :fc  :|c  *  ** 

CSS  CSS  DEPT  CHARGE  ENTRY  COMPL  EST IMTPRCDNG  TOTAL  TIME  CUSTOMER  NAME 
AREA  JOB    NUM        TO        DAY     DAY  WEEK     TIME  RMNING  /AREARESP. 

RETURN  END 


Exhibit  3: 

PRINT  3  LINES  WITH TASK_AREA_NUMBER,  JOB_NUMBER,  JOB_DEPT_NUMBER, 
JOB_PROJ_NUMBER, TASK_ENTRY_DATE , TASK_COMPL_DATE , TASK_ESTIMATED_HOURS , 
INHOUSE_HOURS_FOR_WEEK, TASK_INHOUSE_HOURS+TASK_VENDOR_HOURS , 
TASK_ESTIMATED_HOURS  -  TASK_INHOUSE_KOURS  -  TASK_VENDOR_HOURS  , 
JOB_CUSTOMER, JOB_DESCRIPTION , TASK_EST_VENDOR_HOURS , 

VENDOR_HOURS_FOR_WEEK ,  TASK_VENDOR_HOURS ,  TASK_ASSIGNEE_NAME ,  AND  STAR  THUS 


Exhibit  4: 

FIND  THE  JOB  IN  CSS_JOBS  WITH  JOB_NUMBER  =  PROPOSED_JOB_NUMBER 
IF  ONE  IS  FOUND.  .  . 

CALL  REJECT  (  |  JOB  ALREADY  EXISTS  WITH  SPECIFIED  JOB  NUMBER .  |  ) 
RETURN 
ELSE. . . 


permits  much  more  generality  than  is  illustrated  here,  while  retaining  its  readability  if  entity,  attribute  and  set  names 
are  chosen  with  care. 

The  meaning  of  the  FIND  statement  should  be  clear  even  to  a  reader  without  training  in  EAS-E.  In  general  we  have 
tried  to  design  the  EAS-E  syntax  to  be  self-documenting.  A  number  of  people  without  EAS-E  training  have 
commented  on  the  clarity  of  the  EAS-E  source  program  for  CSS,  though  it  has  very  few  comments  (but  carefully 
chosen  names). 

3.2  Sets  as  Standard  Data  Structures 

In  an  experiment  conducted  by  one  of  the  authors  (10),  subjects  were  asked  to  design  a  program  to  be  implemented  in 
a  higher  level  language  that  would  retrieve  information  from  three  files  in  response  to  certain  specified  types  of 
queries.  Each  of  the  eight  subjects  designed  a  different  data  structure  to  hold  the  information  in  main  storage.  If  the 
designs  were  to  be  implemented,  programs  would  need  to  be  written  to  initialize  each  data  structure  and  manage  the 
pointers  for  all  the  operations  on  it. 

We  argue  that  the  set  facilities  in  EAS-E  can  be  used  to  provide  a  large  variety  of  data  structures.  These  structures 
can  be  used  by  the  programmer  without  having  to  initialize  them  and  maintain  their  pointers.  This  is  taken  care  of  by 
routines  automatically  generated  by  EAS-E.  The  programmer  merely  thinks  in  terms  of  FILE  and  REMOVE 
operations. 

For  example,  a  stack  is  merely  a  LIFO  (last-in-last-out)  set.  Stack  operations  can  thus  be  implemented  by  FILE  and 
REMOVE  statements  on  a  LIFO  set.  Similarly,  queues  and  pipelines  are  FIFO  (first-in-first-out)  sets.  A  tree  can  be 
composed  by  defining  an  entity  called  a  NODE  that  owns  a  set  called  LINKS  and  also  belongs  to  a  set  called  LINKS. 
The  tree  can  be  generated  by  creating  NODES  and  filing  them  into  LINKS  of  other  NODES. 


4.  INTEGRATED  LANGUAGE 


Traditionally,  programming  languages  work  with  database  objects  by  imbedding  a  database  language  within  the  host 
programming  language.   For  example,  a  PL/I  or  COBOL  program  that  works  with  IMS  (4)  contains  explicit  calls  to 
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the  database  language  for  database  functions.  To  work  with  System  R  (1)  the  program  contains  statements  in  a 
special  database  language  called  SQL.  In  these  cases,  the  database  language  can  fetch,  create,  delete  and  update 
database  objects  while  the  host  language  takes  care  of  manipulating  the  objects  in  main  storage. 

EAS-E  is  organized  quite  differently.  The  same  language  can  be  used  to  work  with  database  entities  as  well  as  main 
storage  entities  in  an  entirely  equivalent  manner.  In  general,  database  and  main  storage  variables  can  appear 
anywhere  they  make  logical  sense  in  any  statement  —  READ,  WRITE,  LET,  IF,  FOR  EACH,  etc. 

Integration  of  host  and  database  language  shifts  the  burden  of  interfacing  the  host  language  to  the  database  language 
from  the  programmer  to  the  EAS-E  system.  This  eliminates  a  great  deal  of  the  non-problem-related  code  that  clutters 
up  traditional  programs  and  makes  them  difficult  to  understand.  To  illustrate  this  reduction  in  coding,  we  compare  a 
typical  PL/I  program  that  works  with  an  IMS  database  and  a  PL/I  program  that  works  with  SQL  with  equivalent 
programs  in  EAS-E. 

4.1  Structure  of  a  PL/I  Program  Working  with  IMS 

We  discuss  below  the  structure  of  a  PL/I  batch  program  which  retrieves  data  from  a  detail  file  to  update  a  master 
data  base.  In  EAS-E  such  a  program  would  consist  of  only  a  few  lines.  Let  us  assume  that  the  detail  file  consists  of 
entities  of  type  DETAIL.  The  update  program  would  then  have  the  following  structure: 

FOR  EACH  DETAIL  DO 

FIND  THE  MASTER  WITH  ... 

CALL  UPDATE(DETAIL,MASTER) 
LOOP 

The  FOR  EACH  statement  brings  each  DETAIL  entity  in  turn  from  the  database.  The  FIND  statement  brings  in  the 
appropriate  MASTER  entity.  Changes  made  to  the  database  by  the  UPDATE  routine  are  made  permanent  when  the 
program  ends. 

To  compile  this  program  it  would  by  necessary  to  precede  it  with  the  statement: 

DATABASE  ENTITIES  INCLUDE  MASTER  AND  DETAIL  FROM  .  .  • 

This  would  cause  the  definitions  of  MASTER  and  DETAIL,  which  would  also  be  stored  in  the  database,  to  be  brought 
in  and  used  to  generate  the  the  object  code. 

In  IMS  database  objects  are  called  segments.  The  example  program  works  with  segments  of  type  MASTER  and 
DETAIL.  These  segments  are  stored  in  separate  data  bases.  Access  to  IMS  databases  is  provided  by  making  calls  to 
DL/I  (Data  Language  I)  to  Get,  Insert,  Delete  or  Update  a  specific  segment.  The  call  has  the  structure: 

CALL  PLITDLI(parm-count,  call-function,  db-pcb-name,  i/o-area  [,  ssa  ...  ]); 

The  parameters  of  the  call  are  discussed  in  Exhibit  5  below.  Exhibit  6  illustrates  in  outline  form  the  fundamental 
parts  in  the  structure  of  the  PL/I  batch  program.  Exhibit  7  is  the  explanation  of  the  program  shown  in  exhibit  6. 
Exhibits  5,  6  and  7  are  all  taken  directly  from  (5) 

The  skeleton  program  displayed  in  exhibit  6  is  comprised  of  three  kinds  of  statements.  First,  there  are  the  declarations 
that  set  up  the  parameters  to  be  used  in  the  calls  to  DL/I  (2,  3,  6).  These  are  necessitated  by  the  relative  inflexibility 
of  the  call.  There  is  no  need  to  set  up  such  parameters  in  an  EAS-E  program. 

The  second  set  of  statements  sets  up  the  communication  with  DL,/I  (1,  4,  5,  11,  12).  The  equivalent  function  is 
provided  in  an  EAS-E  program  by  the  DATABASE  ENTITIES  INCLUDE  statement.  In  addition  to  retrieving  the 
definitions  of  the  entities  to  be  accessed  at  compile  time  it  also  causes  the  compiler  to  include  in  the  object  program 
the  instructions  required  to  establish  contact  with  the  database  and  to  test  the  return  codes  from  requests  to  the 
database  manager. 

The  third  part  of  the  skeleton  program  consists  of  the  actual  calls  to  the  database  management  system  (7,  8,  9,  10). 
What  is  not  illustrated  is  the  control  structure  that  must  surround  these  calls  to  check  the  return  codes  and  take  the 
requisite  actions.  After  an  DETAIL  is  processed  the  program  must  jump  back  to  the  call  that  brings  the  next  detail.  If 
the  last  DETAIL  has  been  processed  it  must  terminate.  Here  again,  EAS-E,  being  an  integrated  language,  simplifies 
matters  for  the  programmer.  The  FOR  EACH  statement  fetches  each  entity  of  a  given  type  (or,  as  we  shall  see  later, 
entities  in  a  given  set)  from  the  database.  Main  storage  operations  to  be  performed  on  the  entity  are  specified  in  the 
body  of  the  statement. 

4.2  A  PL/I  Program  Working  With  SQL 

We  now  discuss  a  PL/I  program  working  against  System  R  (1,2)  a  more  modern  database  management  system.  As  we 
shall  see,  the  difficulties  of  interfacing  to  the  database  management  system  have  been  mitigated  but  a  certain  amount 
of  non-problem  related  code  is  still  necessary.  The  PL/I-SQL  program  shown  in  exhibit  8  has  20  lines.  The 
equivalent  EAS-E  program  shown  in  exhibit  9  has  6  lines. 
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parm-count 

The  first  parameter  is  the  address  of  a  four  byte  field  containing  the  number  of  other  parameters  that  are  in 
the  list. 

call-function 

The  second  parameter  contains  the  address  of  a  four  character  field  that  contains  the  DL/I  code  for  the 
function  to  be  performed. 

db-pcb-name 

The  third  parameter  is  the  address  of  a  program  communication  block  (PCB)  that  is  used  for  communication 
between  DL/I  and  the  application  program.  There  is  one  PCB,  which  is  contained  within  the  PSB  [  Program 
Specification  Block  ],  for  each  data  base  being  processed. 

i/o-area 

The  I/O  area  address  is  the  fourth  parameter  in  the  call  statement.  The  I/O  area  is  an  area  in  the 
application  program  in  to  which  DL/I  puts  a  requested  segment  or  from  which  DL/I  takes  a  designated 
segment  ...  .  The  area  must  be  as  long  as  the  longest  segment  to  be  processed.  ...  Segment  data  is  always 
left  justified  within  a  common  area.  Because  of  the  structuring  of  PL/I,  i/o-area  must  be  the  name  of  a  fixed 
length  character  string,  an  area,  a  level  1  in  a  structure,  or  an  array.  If  the  user  wishes  to  deal  with 
substructures  or  elements  of  an  array,  he  should  use  the  DEFINED  or  BASED  attribute. 

Example: 

DECLARE  1  INPUT_AREA 
2  KEY  CHAR(6), 
2  FIELD  CHAR(84); 

ssa 

The  addresses  of  one  or  more  segment  search  arguments  (SSAs)  are  the  final  parameters  in  the  call 
statement.  When  an  application  programmer  requests  DL/I  to  perform  data  base  functions,  it  is  frequently 
necessary  for  him  to  identify  a  particular  segment  by  its  name  and  the  names  of  all  parent  segments  along 
the  hierarchical  path  leading  to  the  desired  segment. 

These  values  do  not  appear  directly  in  the  call  statement  argument  provided  to  DL/I.  Instead,  an  SSA  name 
is  given  that  points  to  an  area  in  the  user's  program  that  contain  the  actual  SSA  values. 

The  SSA  may  consist  of  three  elements:  the  segment  name,  the  command  code,  and  a  segment  qualification 
statement.  The  segment  name  provides  DL/I  with  enough  information  to  define  the  type  of  segment.  The 
command  code  is  optional  and  provides  specification  of  functional  variations  applicable  to  the  call  function. 
...  The  segment  qualification  statement  is  optional  and  contains  information  that  DL/I  uses  to  test  the  value 
of  the  segment's  key  or  data  fields  within  the  data  base  to  determine  whether  the  segment  meets  the  user's 
specifications. 

A  segment  qualification  statement  is  composed  of  three  parts:  a  segment  field  name,  a  relational  operator 
and  a  comparative  value. 

An  unqualified  SSA  is  built  using  a  9  byte  area  with  the  segment  name  occupying  the  leftmost  8  bytes  and  a 
blank  in  position  9  ...  .  [A  qualified  SSA  consists  of  a  field  with  the  segment  name  in  the  leftmost  eight 
bytes  directly  followed  by  a  segment  quaHfication  statement.  ] 

The  qualification  test  is  terminated  as  soon  as  a  segment  type  that  satisfies  the  qualification  test  is  found  in 
the  data  base.  This  procedure  continues  for  all  SSAs  in  a  DL/I  data  base  call  until  the  desired  segment  is 
found. 


Exhibit  5:  Parameters  in  Calls  to  DL/I 
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REF. 

/* 

*/ 

NO. 

/* 

ENTRY  POINT 

*/ 

/* 

*/ 

1 

DLITPLI:  PROCEDURE  ( DB_PTR_MAST , DB_PTR_DETAIL ) 

OPTIONS  (MAIN) ; 

/* 

*/ 

/* 

DESCRIPTIVE  STATEMENTS 

*/ 

/* 

*/ 

DCL  DB  PTR_MAST  POINTER; 

DCL  DB  PTR_DETAIL  POINTER; 

DCL 

FUNC_GU             CHAR (4) 

INITCGU    ')  ; 

DCL 

FUNC_GN             CHAR (4) 

INITCGN    ')  ; 

2 

DCL 

FUNC_GHU           CHAR (4) 

INITCGHU  ')  ; 

DCL 

FUNC_GHN           CHAR (4) 

INIT ('GHN  '  )  ; 

DCL 

FUNC_GNP           CHAR (4) 

INITCGNP  ')  ; 

DCL 

FUNC_GHNP         CHAR ( 4 ) 

INIT  ('GHNP'  ) 

DCL 

FUNC_ISRT        CHAR (4) 

INIT('ISRT') 

DCL 

FUNC_REPL         CHAR ( 4 ) 

INIT  (  'REPL'  ) 

DCL 

FUNC_DLET         CHAR (4) 

INIT  ( 'DLET'  ) 

DCL 

1         QUAL  SSA 

STATIC  UNALIGNED, 

3 

2  SEG_NAME 

CHAR (8)    INIT  ('ROOT         ')  , 

2  SEG_QUAL 

CHARd  )    INITC  (')  , 

2  SEG_KEY_NAME 

CHAR (8)    INIT  ('KEY  '), 

2  SEG_OPR 

CHAR  (2)    INITC   =')  , 

2  SEG_KEY_VALUE 

CHAR(6)  INIT('vvvvvv'), 

2  SEG_END_CHAR 

CHARd  )    INIT  ('  )  '  )  ; 

DCL 

1  UNQUAL_SSA 

STATIC  UNALIGNED, 

2  SEG_NAME_U 

CHAR (8)    INIT  ('NAME         ')  , 

2  BLANK 

CHARd)    INITC  '); 

DCL 

1  MAST_SEG_IO_AREA, 

4 

2  

2  

2  

DCL 

1         DET  SEG_IO_AREA, 
2  

2  

DCL 

2  

1  DB_PCB_MAST 

BASED    (DB_PTR_MAST) , 

2  MAST_DB_NAME 

CHAR (8) , 

2  MAST_SEG_LEVEL 

CHAR ( 2 ) , 

2  MAST_STAT_CODE 

CHAR ( 2 ) , 

5 

2  MAST_PROC_OPT 

CHAR (4) , 

2  FILLER 

FIXED  BINARY  (31,0), 

2  MAST_SEG_NAME 

CHAR (8) , 

2  MAST_LEN_KFB 

FIXED  BINARY  (31,0), 

2  MAST_NO_SENSEG 

FIXED  BINARY  (31,0), 

2  MAST_KEY_FB 

CHAR ( * ) ; 

DCL 

1         DB  PCB_DETAIL 

BASED    (DB_PTR_DETAIL) , 

2  DET_DB_NAME 

CHAR (8) , 

2  DET_SEG_LEVEL 

CHAR ( 2 ) , 

2  DET_STAT_CODE 

CHAR (2) , 

2  DET_PROC_OPT 

CHAR ( 4 ) , 

2  FILLER 

FIXED  BINARY  (31,0), 

2  DET_SEG_NAME 

CHAR  (8) 

2  DET_LEN_KFB 

FIXED  BINARY    (31,0)  , 

2  DET_NO_SENSEG 

FIXED  BINARY  (31,0), 

2  DET_KEY_FB 

CHAR ( * ) ; 

DCL 

THREE           FIXED  BINARY  (31,0 

INITIAL(3) ; 

DCL 

FOUR             FIXED  BINARY  (31,0 

INITIAL(4) ; 

DCL 

FIVE             FIXED  BINARY  (31,0 

INITIAL (5) ; 

DCL 

SIX               FIXED  BINARY  (31,0 

INITIAL(6) ; 

Exhibit  6:   Structure  of  a  PL/I  Program  With  DL/I  Calls 
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/* 

/*       MAIN  PART  OF  PL/I  BATCH  PROGRAM 

*/ 
*/ 

7 
8 

• 

CALL  PLITDLI ( FOUR , FUNC_GU , DB_PCB_DETAIL , 
DET_SEG_IO_AREA,QUAL_SSA) ; 

• 

CALL  PLITDLI ( FOUR , FUNC_GHU , DB_PCB_MAST , 
MAST_SEG_IO_AREA,QUAL_SSA) ; 

9 

• 

CALL  PLITDLI ( THREE , FUNC_GHN , DB_PCB_MAST , 
MAST_SEG_IO_AREA) ; 

10 

• 

CALL  PLITDLI ( THREE , FUNC_REPL , DB_PCB_MAST , 
MAST_SEG_IO_AREA) ; 

1  1 

• 

RETURN; 

END  DLITPLI ; 

1  2 

PL/I  LANGUAGE  INTERFACE 

Exhibit  6    (Contd.):   Structure  of  a  PL/I  Program  With  DL/I 

Calls 

System  R  supports  relational  data  structures.  Relations  can  be  considered  to  be  tables  with  each  tuple  (row)  of  a 
relation  being  a  collection  of  attributes  in  a  given  order.  The  example  application  program  shown  in  exhibit  8  is  taken 
from  (2).  It  updates  the  salary  of  some  of  the  employees  whose  records  are  contained  in  a  relation  called  EMP.  Each 
row  of  EMP  refers  to  a  particular  employee  and  stores  the  EMPNO,  DEFT,  SAL,  RATING  and  possibly  other 
attributes.  Statements  that  start  with  "$"  are  SQL  statements. 

The  first  line  of  the  program  contains  its  name  and  specifies  that  it  has  one  argument:  XDEPT.  The  SQL  statement  on 
line  2  declares  the  main  storage  variables  XEMPNO,  XDEPT,  XSAL,  XRATING  and  XRAISE.  Subsequently  these 
variables,  referred  to  as  $XEMPNO,  $XDEPT,  etc.,  can  be  used  in  SQL  statements. 

The  SQL  statement  on  lines  3  to  7  defines  a  cursor  called  CI  which  consists  of  the  EMPNO,  SAL  and  RATING 
attributes  of  tuples  in  the  EMP  relation  that  meet  the  condition  DEPT  =  $XDEPT.  The  remaining  part  of  the 
program  processes  CI,  one  tuple  at  a  time,  by  moving  the  EMPNO,  SAL  and  RATING  attributes  into  $XEMPNO, 
$XSAL  and  $XRATING  respectively.  The  $OPEN  statement  on  line  8  readies  the  cursor  for  processing  and  binds 
the  value  of  $XDEPT.  The  DO  WHILE  on  line  8  starts  a  perpetual  loop  whose  scope  is  terminated  by  the  END 
statement  on  line  17.  Within  this  loop  the  $FETCH  statement  moves  the  attribute  values  from  the  current  tuple  of 
the  cursor  into  the  appropriate  main  storage  variables.  The  raise  is  then  computed  and  stored  in  $XRAISE.  The 
$UPDATE  statement  on  line  14  stores  the  new  value  of  the  SAL  attribute  in  the  current  tuple  of  CI. 

Line  1 1  tests  the  return  code  from  the  $FETCH  and  jumps  out  of  the  loop  when  the  cursor  is  exhausted.  The 
$CLOSE  statement  closes  CI  and  the  program  ends. 

4.3  Equivalent  Programs  in  EAS-E 

The  function  performed  by  the  program  in  Exhibit  8  can  be  performed  by  the  single  EAS-E  statement: 

FOR  EACH  EMPLOYEE  WITH  DEPT  =  XDEPT 
LET  SALARY  =  .  .  . 

This  brings  each  employee  in  turn  from  the  database  into  main  storage  and  tests  whether  its  DEPT  attribute  equals 
XDEPT.  If  this  is  so,  it  updates  its  salary  as  specified.  The  database  modifications  are  made  permanent  when  the 
program  ends. 

For  compilation,  the  above  statement  must  be  preceded  by: 

DATABASE  ENTITIES  INCLUDE  EMPLOYEE  FROM  •  •  . 

Bringing  all  the  entities  of  a  given  type  into  main  storage  and  processing  those  that  meet  given  conditions  is  exactly 
equivalent  to  processing  a  relation  in  a  relational  database.  In  a  network  database  we  can  be  more  efficient.  If  the 
selection  criterion  is  one  that  is  commonly  used,  such  as  employees  within  a  department,  then  the  EMPLOYEE 
entities  should  be  filed  into  sets  owned  by  the  DEPARTMENT  entities.  With  this  structure,  only  the  EMPLOYEES  in 
the  particular  department  are  brought  into  main  storage. 
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The  following  explanation  relates  to  the  reference  numbers  along  the  left  side  of  [  Exhibit  6  ]. 

1.  This  is  the  main  entry  point  to  a  PL/I  batch  program.  After  the  DL/I  control  program  has  loaded  and 
relocated  the  PSB  for  the  program,  it  gives  control  to  this  entry  point.  The  FSB  contains  all  the  PCBs 
used  by  the  program.  The  entry  point  statement  of  the  batch  program  must  contain  the  same  number  of 
names  in  the  same  sequence  as  there  are  PCBs  in  the  PSB. 

2.  Each  area  defines  one  of  the  call  functions  used  by  the  PL/I  batch  program.  Each  character  string  is 
defined  as  4  alphameric  characters,  with  a  value  assigned  for  each  function  ...  .  Other  constants  may  be 
defined  in  the  same  manner.  Standard  definitions  could  be  stored  in  a  source  library  and  included  using  a 
%INCLUDE  statement. 

3.  A  structure  declaration  defines  each  SSA  used  by  the  problem  program.  The  unaligned  attribute  is 
required  for  SSA  data  interchange  with  DL/I.  The  SSA  character  string  must  reside  contiguously  in 
storage.  Assignment  of  variables  to  key  values,  for  example,  could  result  in  the  construction  of  an  invahd 
SSA  if  the  key  value  has  the  ahgned  attribute. 

A  separate  SSA  structure  is  required  for  each  segment  type  accessed  by  the  program  because  the 
key-value  fields  should  be  different.  Once  the  fields  other  than  key-value  are  initialized,  they  should  not 
have  to  be  altered. 

A  9  byte  area  should  be  reserved  for  use  as  an  unqualified  SSA.  Before  issuing  an  unquaUfied  call,  a 
segment  name  is  moved  into  this  field. 

4.  The  segment  I/O  areas  are  defined  as  structures. 

5.  One  level  1  declarative  ...  describes  as  a  structure  the  data  base  PCB  entry  for  each  input  or  output  data 
base.  It  is  through  this  description  that  a  PL/I  program  may  access  the  status  codes  after  a  DL/I  call. 

6.  This  statement  is  used  to  identify  a  binary  number  (fuUword)  that  represents  the  parameter  count  of  a  call 
to  DL/I.  ... 

7.  and  8.  These  are  typical  calls  to  retrieve  data  from  a  data  base  using  a  qualified  SSA. 

Prior  to  execution  of  the  call  the  SEG  KEY  VALUE  field  of  the  SSA  must  be  initialized  if  a  fully 

qualified  SSA  is  required.  For  a  call  using  an  unqualified  SSA,  the  segment  name  field  must  be  moved  to 
one  of  the  9-byte  UNQUAL_SSA  areas. 

Immediately  following  the  call  the  status  code  field  of  the  PCB  must  be  checked  to  determine  the  results 
of  the  call.  ... 

9.  This  is  a  typical  call  to  retrieve  data  from  a  data  base  using  no  SSA.  This  call  is  also  a  HOLD  call  for 
subsequent  delete  or  replace  operation. 

10.  This  call  is  used  to  replace  data  in  a  data  base  with  data  from  a  PL/I  batch  program. 

11.  This  RETURN  statement  causes  the  batch  program  to  return  control  to  DL/I. 

12.  [A  language  interface  module  must  be  link-edited  to  the  program  to  provide  a  common  interface  to 
DL/I.  The  specific  module  used  and  the  procedure  for  link-editing  depend  on  the  operating  environment.] 


Exhibit  7:  Comments  on  The  PL/I-DL/I  Program  Structure 
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1  PAYRAISE:   PROC ( XDEPT ) ; 

2  $DCL  (XEMPNO,  XDEPT,  XSAL, XRATING, XRAISE) ; 

3  $LET  CI  BE 

4  SELECT       EMPNO,  SAL,  RATING 

5  INTO  $XEMPNO,   $XSAL,  $XRATING 

6  FROM  EMP 

7  WHERE         DEPT  =  $ XDEPT; 

8  $OPEN  CI ; 

9  DO  WHILE   ('1'  B)  ; 

10  $FETCH  CI ; 

11  IF  SYR_CODE-i=0  THEN  GO  TO  WRAPUP; 

12  /*  COMPUTE  XRAISE  BASED  ON 
1  3  XSAL  AND  XRATING  */ 

14  $UPDATE  EMP 

15  SET  SAL  =  SAL  +  $XRAISE 

16  WHERE  CURRENT  OF  CI  ; 

1 7  END ; 

1 8  WRAPUP ; 

19  $CLOSE  CI ; 

20  END  PAYRAISE; 


Exhibit  8  :  An  Example  PL/I  Program  With  SQL  statements 


Exhibit  9  shows  an  EAS-E  subroutine  that  updates  the  salary  of  all  employees  in  a  given  department.  It  uses  a  FOR 
EACH  statement  which  is  a  little  different  from  the  one  used  in  the  above  example:  it  processes  all  the  entities  in  a 
set  rather  than  all  the  entities  of  a  certain  type. 

Exhibit  9: 

ROUTINE  PAYRAISE (XDEPT) 

DEFINE  XDEPT  AS  A  REFERENCE  VARIABLE 

FOR  EACH  EMPLOYEE  IN  EMPLOYEES  ( XDEPT ) 

LET  SALARY  =  .  .  . 
RETURN 
END 

For  compilation,  the  above  subroutine  would  have  to  be  preceded  by 

DATABASE  ENTITIES  INCLUDE  EMPLOYEE  AND  DEPARTMENT  FROM  . . . 

Let  us  now  discuss  the  actions  caused  by  the  above  program  in  more  detail.  The  DATABASE  ENTITIES  INCLUDE 
statement  specifies  that  the  program  will  be  working  with  the  database  entities  EMPLOYEE  and  DEPARTMENT.  In 
addition,  it  declares  EMPLOYEE  and  DEPARTMENT  as  reference  variables  which  can  be  used  to  point  to 
EMPLOYEE  and  DEPARTMENT  entities  in  main  storage.  During  compilation  the  definitions  of  EMPLOYEE  and 
DEPARTMENT  are  brought  from  the  database  and  the  information  contained  in  them  is  used  to  generate  object  code 
that  can  manipulate  their  attributes  in  main  storage. 

The  DEFINE  statement  defines  XDEPT  as  a  local  reference  variable.  When  the  routine  is  called,  XDEPT  must  refer 
to  a  database  entity  of  type  DEPARTMENT.  The  next  statement,  FOR  EACH  EMPLOYEE  IN 
EMPLOYEES(XDEPT),  instructs  the  compiled  EAS-E  program  to  have  the  reference  variable  "EMPLOYEE"  point 
in  turn  to  each  member  of  the  set  called  EMPLOYEES  that  is  owned  by  the  DEPARTMENT  pointed  to  by  XDEPT. 
This  statement  could  be  followed  by  an  arbitrary  number  of  selection  phrases  (such  as  the  WITH...  phrase  in  the 
example  above)  that  would  instruct  the  executing  program  to  test  the  EMPLOYEE  and  make  sure  that  it  met  specified 
conditions.  For  each  EMPLOYEE  thus  selected,  the  program  would  update  the  SALARY  attribute  in  the  manner 
specified. 

5.  SUMMARY 


This  paper  has  discussed  the  Entity,  Attribute  and  Set  model  and  described  a  simple  method  of  documenting  the  EAS 
status  of  a  system  or  application.  It  has  also  discussed  the  EAS-E  language  and  compared  its  facihties  with  other 
languages  from  the  point  of  view  of  compactness  and  readability.  We  have  shown  that  EAS-E  programs  are  much 
shorter  than  equivalent  programs  in  other  languages  and  contain  much  less  non-problem-related  code.  Since  the 
powerful,  English-like  commands  in  EAS-E  programs  accurately  mirror  the  steps  taken  by  the  programmer  to  solve 
the  problem,  EAS-E  can  be  thought  of  as  executable  documentation. 
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ADD:    An  Automated  Tool  For  Program  Design  and  Documentation 

T.C.  Ting* 

Worcester  Polytechnic  Institute 

An  approach  which  integrates  the  activities  of  software  design  and  documenta- 
tion is  proposed,  described,  and  discussed.    An  automated  tool  called  ADD  which 
uses  a  data  dictionary  system  is  suggested  to  support  this  approach.    The  unified 
approach  not  only  offers  solutions  to  some  of  the  important  documentation  problems, 
but  it  provides  a  structured  means  for  better  program  design  and  coding.  Program 
design  process  is  enhanced  and  guided  by  a  structured  "design  template".  Program 
design  documents:  are  generated  automatically  to  serve  as  "blueprints"  for  program- 
ming.   The  use  of  a  "program  coding  template"  provides  a  structure  for  coding. 
Program  module  interface  conditions  are  automatically  generated  and  controlled 
from  the  design  specifications.    Program  modules  are  tested  by  using  the  pre- 
designed and  stored  test  data  to  certify  their  correctness. 

The  structure  of  the  tool  is  illustrated.    How  the  automated  tool  may  be  used 
and  the  benefits  of  such  an  automated  tool  are  discussed. 

Keywords:    Automated  tools,  program  design,  program  documentation,  program  docu- 
ment standardization,  program  testing,  software  engineering. 

*The  author  is  also  a  part-time  computer  scientist  at  the  Institute  for  Computer 
Sciences  and  Technology,  the  National  Bureau  of  Standards.    This  paper  was  not 
prepared  while  on  official  duty  and  it  does  not  reflect  any  official  position  of 
the  National  Bureau  of  Standards. 

1.  INTRODUCTION 

Studies  of  large  computer  software  systems  have  identified  several  major  problems. 
One  of  the  most  serious  concerns  is  the  sad  state  of  computer  software  documentation 
(GAO  1974),    The  literature  reports  many  suggestions  and  recommendations  on  the  contents, 
methods,  and  formats  of  software  documentation  (Brewer  1976,  Gey  1973,  Gass  1979).  Stan- 
dardized software  documentation  procedures  and  formats  have  been  adopted  by  many  organiza- 
tions including  the  Federal  Government  (NBS  1976,  1980).    However,  the  problem  remains. 

The  author  is  a  strong  believer  that  in  order  to  yield  a  good  software  product,  the 
software  documentation  activities  must  be  integrated  into  the  whole  software  development 
process.    Program  documentation  is  an  active  part  of  program  development.    It  should  not  be 
treated  as  a  passive  task  of  simply  recapturing  the  descriptions  of  an  already  developed 
program.    Good  program  design  leads  to  good  documentation.    Good  documentation  contributes 
to  good  design. 

An  organized  and  structured  program  design,  together  with  straightforward  program  im- 
plementation techniques,  can  immensely  ease  the  documentation  task  (Gey  1976).  Dijkstra 
stated  that  good  programming  recognizes  how  to  avoid  unmanageable  complexity  (Dijkstra  1975). 
A  well -structured  top-down  design  decomposes  a  large  and  complicated  problem  into  multiple 
units  of  comprehensible  and  manageable  subproblems  and  sub-subproblems.    These  sub-divided 
units  can  be  organized  into  program  modules.    These  modules  are  the  basic  building  blocks 
for  the  program  and  they  can  be  individually  designed,  implemented,  and  tested.    The  pro- 
posed approach  with  an  automated  tool  supports  the  structured  program  design  and  implementa- 
tion. 

This  paper  reports  and  discusses  the  concepts  of  the  automated  program  design  and  docu- 
mentation approach.    Four  types  of  software  documents  are  necessary  for  a  software  system. 
These  documents  are  prepared  for  management,  users,  operational  personnel,  and  programming 
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analysts.    However,  the  documentation  discussed  in  this  paper  concerns  only  the  type  of 
documents  for  program  analysts.    These  documents  are  used  in  assisting  program  design,  im- 
plementation, and  maintenance. 

An  automated  program  design  and  documentation  tool  called  ADD,  Automated  Design  and 
Documentation,  is  suggested  and  illustrated.    ADD  uses  a  data  dictionary  and  program  design 
and  coding  templates.    It  provides  a  means  for  the  designer  to  have  an  organized  and  struc- 
tured approach  for  program  design.    The  results  of  this  approach  not  only  provide  a  set  of 
comprehensive  program  documents,  but  produce  a  good  program  design. 

ADD  automatically  generates  program  structural  and  flow  diagrams,  and  individual  pro- 
gram module  description  sheets.    These  documents  can  help  the  designer  to  verify  the  design, 
and  they  serve  as  "blueprints"  for  programming.    A  program  coding  template  is  used  to  help 
in  setting  up  a  structure  for  programming.    Important  program  module  interface  conditions 
such  as  input  and  output  variables    are  automatically  generated  from  the  design  which  is 
stored  in  the  data  dictionary.    The  validity  of  the  implementation  is  checked  automatically 
and  any  conflict  must  be  resolved  between  the  designer  and  programmer.    Test  data  provided 
by  the  designer  are  part  of  the  program  documentation  and  they  are  used  to  certify  the  pro- 
gram during  the  program  testing  and  maintenance  stages. 

One  of  the  most  difficult  problems  of  software  documentation  is  the  ever-changing  en- 
vironment of  a  software  system.    The  high  rate  of  software  maintenance  activities  and  pro- 
gram patches  make  any  existing  software  document  quickly  out-of-date.       One  of  the  major 
benefits  of  ADD  is  to  reduce  this  problem.    The  organization  and  structure  of  the  tool  are 
presented  and  discussed.    The  benefits  of  the  proposed  approach  and  the  automated  tool,  ADD, 
are  discussed. 


2.    PROBLEMS  OF  SOFTWARE  DOCUMENTATION 

Documentation  is  an  area  of  the  software  engineering  field  where  the  professional  pro- 
gram analyst  is  not  very  competent.    Almost  no  one  has  had  the  actual  opportunity  to  learn 
to  document.    First  of  all,  university  computer  science  curricula  have  never  paid  any 
serious  attention  to  program  documentation.    A  large  number  of  software  packages  have  been 
produced  by  universities  from  student  and  faculty  research  and  development  projects.  These 
software  products  have  greatly  contributed  to  computer  software  advancements.  However, 
software  documents  for  these  products  are  almost  non-existent  or  too  poor  to  be  useful. 
Students  are  usually  taught  to  code.    Emphasis  is  often  misplaced  on  the  programming  lan- 
guage instead  of  design  and  programming  techniques.    Not  much  stress  is  laid  on  program  de- 
sign and  documentation.    Due  to  the  classroom  environment,  usually  only  small,  simple  and 
trivial  program  exercises  can  be  assigned.    These  assignments  often  do  not  justify  applying 
a  rigid  program  development  methodology.    Students  usually  work  alone  with  no  requirement 
to  cooperate  with  others.    In  many  cases,  instructors  discourage  or  even  prohibit  students 
working  cooperatively  on  programming  assignments.    Student  programs  are  often  required  to 
run  only  once  for  some  arbitrarily  selected  sets  of  data  for  grading  purposes.    Under  such 
circumstances,  no  incentive  is  given  to  the  design  and  to  the  documentation  of  the  program. 

Documentation  is  usually  treated  as  an  add-on  task  to  the  software  development  project. 
Software  development  staff  are  often  assigned  to  a  new  project  immediately  after  the  pro- 
gram is  running  and  before  the  documentation  has  been  completed.    Frequently,  time  pro- 
vided for  documentation  is  not  sufficient.    Many  program  documents  are  unverified  as  to 
their  completeness  and  correctness.    The  importance  of  the  documentation  is  considered  only 
as  an  afterthought  whenever  some  difficulties  have  occurred  during  the  program  maintenance 
stage.    It  is  very  difficult  to  convince  the  management  and  project  development  staff  that 
without  the  completion  of  program  documentation  the  project  has  not  been  completed.  The 
problem  is  compounded  by  the  fact  that  many  software  development  methodologies  consider 
documentation  activities  separately  from  the  program  development.    Documentation  is 
usually  done  after  the  program  has  been  completed. 

The  most  difficult  problem  of  program  documentation  is  the  ever-changing  software 
environment.    Continuously  changing  program  requirements  or  computing  facilities  makes  it 
very  tough  and  laborious  for  software  maintenance  personnel  to  keep  software  running 
smoothly.    Frequently,  a  program  has  to  be  modified  for  whatever  the  reasons  may  be.  The 


96 


numerous  program  patches  make  any  existing  program  document  quickly  out-of-date.  The 
document  is  often  not  immediately  updated.    It  is  very  difficult  for  the  busy  maintenance 
staff  who  is  under  pressure  to  fix  the  program  to  consider  concurrently  changing  the  pro- 
gram document.    Poor  documentation  causes  the  maintenance  personnel  to  be  even  busier. 

The  continuing  proliferation  of  novel  hardware  devices,  programming  languages,  and  add 
itional  applications  complicates  further  the  task  of  software  design  and  documentation.  It 
is  difficult  to  formulate  any  documentation  standard  and  procedure  that  can  really  work. 

Automation  of  program  design  and  documentation  offers  some  possible  solutions  to  some 
of  the  above  mentioned  problems. 


3.    PURPOSES  AND  TYPES  OF  SOFTWARE  DOCUMENTATION 

Generally  speaking,  four  types  of  software  documentations  are  needed  for  different 
purposes  (Gass,  1981).    They  are  prepared  for  user's,  operational  personnel,  management,  and 
program  analysts. 

User  documentation  is  a  medium  which  provides  for  communications  between  the  user  and 
software  designer.    It  provides  users  with  instructions  for  using  the  system,  such  as  de- 
scriptions on  the  contents  and  forms  of  input  and  output  of  the  software.    Ideally,  it 
should  provide  answers  to  all  of  the  user's  questions  concerning  the  use  of  the  system. 

Operational  documentation  specifies  requirements  and  steps  necessary  for  operating  the 
software.    It  is  prepared  for  the  operational  personnel  including  data  preparation,  data 
entry,  security  and  integrity  checking,  just  to  name  a  few. 

Software  documentation  for  management  is  a  general  statement  of  the  conceptual  design 
of  the  proposed  system  (prepared  for  management  decision-making).    It  specifies  the  func- 
tional and  performance  requirements  of  the  system  and  resources  required  for  the  develop- 
ment and  later  operation  of  the  system  such  as  personnel,  financial,  and  computing  re- 
sources.   The  final  document  is  the  basis  for  the  development  of  the  system. 

This  paper  discusses  mainly  the  software  documentation  for  the  program  analyst.  We 
will  refer  to  this  type  of  documentation  as  program  documentation.    It  describes  the  de- 
tailed design  and  implementation  of  the  program.    It  provides  technical  descriptions  for 
the  program.    It  has  a  set  of  functional  specifications.    It  defines  all  input  and  output 
for  the  whole  program  as  well  as  its:  subprograms.    It  lists  the  test  data  and  their  ex- 
pected results.    It  provides  detailed  descriptions  on  all  data  files  and  records.  It 
specifies  the  environment  under  which  the  program  is  to  operate. 

Program  documentation  assists  the  technical  staff  to  develop  and  to  maintain  programs. 
It  is  a  record  of  the  program  design  and  implementation,  and  it  is  a  technical  reference  to 
the  program. 


4.    SOFTWARE  DEVELOPMENT  AND  DOCUMENTATION 

Software  documentation  activities  are  the  integral  part  of  software  development. 
Documentation  activities  are  involved  in  every  stage  of  the  software  development  life  cycle 
problem  definition,  system  design,  programming,  testing,  and  maintenance.    Software  docu- 
mentation keeps  a  formal  record  of  the  results  of  each  major  software  development  step. 

Good  software  documentation  imposes  a  structured  approach  on  the  problem  definition. 
It  helps  in  defining  the  problem  in  terms  of  the  input,  output,  and  functions  of  the  pro- 
gram.   It  keeps  track  of  the  process  of  problem  decomposition  during  the  design  phase.  It 
helps  to  organize  the  multiple  levels  of  subproblems  into  program  modules.    It  offers  a 
structure  for  systematic  design  of  each  program  module  including  the  functional  specifica- 
tion, input  and  output  variables,  data  files,  the  logical  steps  to  transform  from  input  to 
the  desired  output,  and  the  necessary  testing  data  and  their  expected  results. 

Software  documents  generated  during  the  design  phase  are,  in  fact,  the  "blueprints" 
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for  coding.    The  program  listings  are  the  program  implementation  documents  which  describe 
the  actual  programs  in  a  chosen  programming  language. 

Program  design  and  implementation  documents  are  the  natural  products  of  the  software 
development  life  cycle.    Program  documentation  enhances  the  program  development  process  for 
better  design  and  better  implementation  of  the  program,  when  the  emphasis  is  on  the  design 
but  not  on  coding.    Software  development  includes  software  documentation.    Software  docu- 
mentation is  an  integral  and  inseparable  part  of  the  software  development  task. 

During  the  software  maintenance  stage,  program  documents  are  obviously  essential.  Any 
modification  made  to  the  program  must  immediately  be  recorded  into  the  document  so  that 
the  document  is  always  an  accurate  and  correct  description  of  the  program. 


5.    AUTOMATION  OF  PROGRAM  DOCUMENTATION 

The  software  profession  has  successfully  automated  many  systems  for  others.    It  has 
not,  however,  been  too  successful  for  itself.    Program  documentation  is  one  of  the  areas  in 
which  automation  may  be  fruitful.    The  software  profession  needs  automated  documentation 
tools  for  enhancing  software  development.    Among  the  four  types  of  software  documentation, 
program  documentation  is  probably  the  best  candidate  for  immediate  automation. 

This  section  discusses  the  proposed  approach  and  ADD.    The  overall  organization  and 
involvement  of  ADD  is  illustrated  in  Figure  1. 

5.1  Use  of  Data  Dictionary    System  for  Recording  Program  Design  Specifications 

A  data  dictionary  system  has  demonstrated  its  usability  in  data  management  (Lefkowitz, 
1977).    This  paper  presents  a  new  approach  by  using  the  data  dictionary  system  in  program 
design  and  documentation.    In  a  top-down  program  design  process,  the  problem  to  be  solved 
by  the  proposed  system  is  functionally  decomposed  into  smaller  subproblems.    These  de- 
composed units  are  organized  into  many  interrelated  program  modules  for  implementation. 
Two  types  of  modules  are  involved:    terminal  and  drive  modules.    These  [nodules  are  hier- 
archically organized  in  a  program  tree  diagram  which  expresses  the  hierarchical  relation- 
ship of  modules  by  functional  decomposition.    Modules  can  also  be  represented  in  flow  dia- 
grams to  show  the  process  flow  pattern  of  the  program.    These  program  modules  are  the 
basic  building  blocks  for  the  program. 

For  each  program  module,  the  designer  analyzes  the  functional  specifications,  and  de- 
termines   the  input  and  output  variables,  the  major  logical  steps  to  transform  from  input 
to  output,  the  names  of  other  modules  called  by  this  module  for  performing  the  functions, 
the  test  data  and  their  expected  results.    A  data  dictionary  system  can  be  used  to  store 
these  design  specifications.    The  following  categories  of  information  are  stored  in  the 
data  dictionary: 

Name  and  type  of  module 

Functional  specifications 

Input  and  output  variables 

Names  and  descriptions  of  data  files 

Names  and  other  program  modules  called  by  this  module 

Major  logical  steps  of  the  process 

Test  data  and  their  expected  results 

5.2  A  Program  Design  Template 

A  program  design  template  is  proposed  to  assist  the  designer  for  entering  program 
module  design  specification.    It  provides  a  structure  so  that  the  designer  can  proceed  with 
the  design  in  an  organized  and  systematic  manner.    It  helps  the  designer  to  completely 
specify  each  program  module  area  by  area.    Areas  to  be  specified  are  discussed  below. 

5,2,1    Name  and  Type  of  Module 

The  name  of  the  module  is  assigned  by  the  designer  using  the  established  naming 
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Figure  1.  ~  The  Organization  of  ADD. 
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convention  or  standard  adopted  by  the  organization.  The  type  of  module  is  specified,  and 
it  may  be  one  of  the  following: 


A  block 
A  PARAGRAPH 
A  PROCEDURE 
A  Macro 

A  REMOTE  block 

A  function  subprogram 

A  subroutine  subprogram 

The  above  is  an  example  and  it  is  by  no  means  a  complete  list. 

5.2.2    Functional  Specifications 

The  functions  to  be  performed  by  the  module  should  be  described  in  English  or  in 
mathematical  logic.    It  is  desirable  that  a  single,  meaningful,  but  not  too  trivial,  func- 
tion is  to  be  performed  by  a  program  module. 

The  designer  must  specify  the  major  processing  steps  by  using  the  pseudo  code.  Only 
the  main  ideas  of  approaches  are  required.  An  example  of  the  functional  specification  is 
provided  in  Figure  2. 


FINDING  ROOTS  OF  h  QUADRATIC  EQUATION. 

INPUT  VARIABLES  ARi:  A,B,    AND  C.      THE  RESULTS  MAY  BE: 

1.  NO  ROOTS 

2.  ONE  REAL  ROOO' 

3.  TWO  REAL  ROOTS 

4  .      TVJO  COMPLEX  ROOTS 


MAJOR  STEPS: 

INPUT 

IF  A=0 

THEN  IF  B=0 

THEN   NO  ROOT 

ELSE  ONE  ROOT  (ONERT) 

ELSE  IF  B**2  LESS  THAN  4AC 

•vnrr,  two  roots  (tv;okt) 

ELSE  TWO  COMPLEX  ROOTS  (COMPRT) 


Figure  2.  —  An  Example  of  the 
Functional  Specification. 
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5.2.3  Input  and  Output  Variables 

For  each  program  module,  the  designer  must  clearly  specify  the  input  and  output 
variables.    This  is  one  of  the  most  important  module-to-module  interface  conditions.  The 
following  information  must  be  provided: 

Name  of  each  variable. 
Type  of  each  variable. 

Order  of  the  input  and  output  variables  appears  on  the  argument  list, 
a  common  block,  or  an  I/O  data  structure.    If  a  named  common 
block  is  used  the  name  of  the  block,  along  with  names  of 
variables  in  desired  order,  must  be  specified. 

Initial  and  range  of  values,  if  any,  for  each  input  and  output 
variable. 

Coding  scheme,  if  any,  for  each  input  and  output  variable. 

5.2.4  File  Names  and  File  Descriptions 

Data  files  commonly  accessed  by  different  program  modules  must  have  their  file  des- 
criptions stored  in  the  file  description  modules  in  the  data  dictionary.    (File  modules  are 
identified  by  their  respected  file  names.)    Each  file  description  module  includes  detailed 
information  on  the  file  name,  file  organization,  file  protection  methods,  data  records  and 
their  their  descriptions,  etc. 

5.2.5  Other  Modules  Called  by  the  Module 

The  designer  must  specify  the  names  of  those  modules  which  are  called  by  this  module. 

5.2.6  Test  Data  and  Their  Expected  Results 

Based  on  the  functional  specifications,  the  designer  should  design  a  complete  set  of 
test  data.    For  each  data  group,  the  expected  results  should  be  provided.  Additional 
testing  conditions,  if  any,  which  are  necessary  for  testing  the  robustness  of  the  program 
module    should  also  be  provided.    The  error  handling  conditions  or  error  return  codes 
should  be  specified. 

5.3    Automatic  Generation  of  Program  Design  Documents 

Information  of  each  program  module  stored  in  the  data  dictionary  can  be  automatically 
scanned  to  produce  a  set  of  program  structural  and  flow  diagrams.    Individual  program 

module  description  sheets  can  also  be  generated.    These  software  design  documents  are  the 
bases  for  programming.    They  can  be  treated  as  "blueprints"  to  the  program. 

5.3.1    Generation  of  Program  Structural  Diagram 

The  tree-like  program  structural  diagram  can  be  generated  by  scanning  the  names  of 
modules  called  by  other  modules.    The  designer  may  use  this  diagram  to  verify  the  functional 
decomposition  of  the  program. 

The  designer  can  modify  the  design.    An  updated  program  structural  diagram  can  be  re- 
generated without  much  difficulty.    An  example  of  the  structural  diagram  is  provided  in 
Figure  3. 


101 


OUADRT 


ONERT 


I  I 

I  I 

I  TWORT  I 

I  I 


I 

j  COMPRT 
I 


Figure  3.  ---  An  Example  of  the 
Generated  Structural  Diagram. 


5.3.2    Generation  of  Program  Flow  Diagrams 

Program  flow  diagram  for  each  program  module  can  be  generated  by  scanning  the  pseudo 
code.    Pseudo  code  consists  of  only  two  types  of  statements:    decision  and  processing 
statements.    It  is  not  too  difficult  to  develop  a  software  package  which  can  generate  flow 
diagrams  from  pseudo  code. 

Flow  diagrams  can  describe  processing  logic  at  different  levels  of  abstraction.  At 
the  top  of  the  program  structure,  the  flow  diagram  reflects  the  function  of  the  whole  pro- 
gram in  a  highly  abstract  form.    It  may  contain  only  several  simple  decisions  for  activating 
several  major  sub-program  modules.    However,  at  the  lowest  level,  the  processing  logic  of  a 
small  terminal  module  is  described.    Such  a  module  should  have  only  a  simple  function  to 
perform.    The  generation  of  such  a  flow  diagram  may  not  even  be  necessary.    However,  it 
should  not  be  difficult  to  produce    such  a  diagram.    In  a  well -structured  and  modularized 
design,  if  such  a  logic  at  the  terminal  module  level  is  too  complicated  to  describe,  further 
decomposition  is  then  necessary.    An  example  of  the  flow  diagram  is  illustrated  in  Figure  4. 
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Figure  4.  --  An  Example  of  the 
Generated  Flow  Diagram. 
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To  flowchart  or  not  to  flowchart  is  a  controversial  issue.    Some  people  deny    the  need 
for  flowcharting,  while  others  may  consider  flow  diagrams  necessary.    It  may  be  a  good  rule 
of  thumb  that  at  the  terminal  module  level  if  it  didn't  require  a  flow  diagram  to  code  the 
module,  it  doesn't  need  a  flow  diagram.    However,  at  the  higher  level,  it  needs  a  flowchart 
to  keep  track  of  what  the  designer  is  doing.    The  logical  sequence  of  program  modules  must 
be  made  clear  so  that  correct  assumptions  are  made. 

Flow  diagrams  or  pseudo  codes  are  useful  to  the  designer.    The  logical  processing  se- 
quences can  be  verified  without  worrying  about  the  details  in  actual  programming.  These 
automatically  generated  diagrams  help  the  designer  to  carry  out  the  top-down  design  of  the 
program.    The  designer  need  not  consider  the  burden  of  producing  these  diagrams. 

Program  flow  diagrams  can  assist  the  programmer  in  coding  the  program  module  into  what- 
ever the  chosen  programming  language  may  be.    When  coding  at  the  terminal  module  level,  the 
programmer  may  exercise  his  or  her  own  discretion  in  the  implementation  of  the  function. 
However,  at  the  higher  level,  the  drive  module  may  require  the  process  to  follow  a  certain 
sequence  as  designed,  since  several  modules  may  be  involved  to  perform  the  function  in  a 
particular  order.    These  program  modules  may  be  implemented  by  several  programmers,  and  they 
must  work  according  to  the  design. 

The  flow  diagram  helps  the  program  maintenance  staff.    They  can  use  these  diagrams  to 
understand  on  what  the  coded  program  listings  are  based, 

5.4    Generation  of  Program  Module  Description  Sheets 

Program  module  description  sheets  can  be  automatically  generated  by  simply  printing  out 
the  sorted  information  in  a  preselected  format.    These  description  sheets  can  be  used  along 
with  the  structural  and  flow  diagrams  to  provide  detailed  specifications  for  each  program 
module.    Some  of  the  information  described  below  have  particular  significance. 

An  example  of  the  program  module  description  sheet  is  provided  in  Figure  5. 


5.4.1  Interface  Conditions  Between  Program  Modules 

The  module-to-module  interface  conditions  can  be  clearly  specified.    On  each  program 
module  description  sheet,  the  input  and  output,  the  modules  called,  and  the  data  files  are 
detailed.    This  information  is  vitally  important  to  the  program  development,  especially 
when  a  large  program  is  involved. 

5.4.2  Program  Testing  and  Test  Data 

To  insure  that  each  module  performs  as  it  is  expected,  a  wel 1 -designed  test  data  set 
must  be  provided.    These  data  are  developed  by  the  designer.    They  are  used  to  check  the 
program  implementation.    During  the  maintenance  phase,  after  each  modification  of  the  pro- 
gram, all  modules  involved  must  be  tested  by  using  these  pre-designed  and  stored  test 
data.    These  tests  can  insure  to  some  degree  that  the  modification  is  valid  and  no  addi- 
tional bugs  have  been  introduced.    This  is  obviously  an  important  task.    However,  such  a 
task  has  not  been  handled  very  well  by  many  data  processing  organizations.    Often,  several 
bugs  will  be  introduced  after  a  simple  modification  to  the  program.    New  test  data  can  be 
introduced  if  necessary,  and  they  should  be  stored  with  the  other  test  data  in  the  data 
dictionary. 

5. 5    Other  Design  Aids 

Other  design  aids  such  as  cross  references  of  various  kinds  can  also  be  generated  from 
the  data  dictionary.    Details  of  this  area  have  not  been  carefully  investigated  at  this 
time.    They  will  be  reported  in  our  forthcoming  papers. 
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NAME  OF  THE  MODULE:  QUADRT 
TYPE  OF  THE  MODULE:  SUBROUTINE 
SPECIFICATIONS: 

FIND  ROOTS  OF  A  QUAURATIC  EQUATION 

INPUT  VARIABLES  ARE  A,B,C.     THE  RESULTS  MAY  BE: 

1.  NO  ROOTS 

2.  ONE  REAL  ROOT 

3.  TWO  REAL  ROOTS 

4.  TWO  COMPLEX  ROOTS 

MAJOR  STEPS: 
INPUT 

IF  A=0 

THEN  IF  8=0 

THEN  NO  ROOT 

ELSE  ONE  ROOT  (ONERT) 

ELSE  IF  B**2  LESS  THAN  4 AC 

THEN  TWO  ROOTS  (TWORT) 
ELSE  COMPLEX  ROOTS  (COMPRT) 

OUTPUT 

INPUT  AND  OUTPUT  VARIABLES: 


VARIABLE  VALUE  COPING 

NAME         DESCRIPTIONS  TYPE  INIT     MIN     MAX  SCHEME 

A  INPUT  VARIABLE  REAL 

B  INPUT  VARIABLE  REAL 

C  INPUT  VARIABLE  REAL 

RT  ROOT  OF  BX+C=0  REAL 

RTl  REAL  ROOT  ONE  REAL 

RT2  REAL  ROOT  TWO  REAL 

IMl  IMAGINARY  ONE  REAL 

IM2  IMAGINARY  TWO  REAL 

IND  RESULT  INDICATOR  INTEGER  0=NO  ROOT 

1=0NE  ROOT 
2=TW0  ROOTS 
3=C0MPLEX 


DATA  FILES: 

OTHER  MODULE  CALLED: 

ONERT,   TWORT,  COMPRT 

TEST  DATA  AND  EXPECTED  RESULTS: 

A  B  C  RT  RTl  RT2  IMl  IM2  IND 

0.0  -5.0  2.0  -4.25      -5.75  2 

4.0  4.0  2.0  -0.5         -0.5         1.0  1.0  3 

0.0  2.0  4.0  -.05  1 

0.0  0.0  5.0  0 


Figure  5.  --  An  Example  of  the  Program 
Module  Description  Sheet. 
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5.6    A  Program  Coding  Template 

A  program  coding  template  is  suggested  for  use  by  the  programmer  in  the  implementation 
of  the  program.    The  program  coding  template  can  be  implemented  within  the  "Editor".  Dif- 
ferent types  of  program  coding  templates  are  necessary  for  different  programming  languages. 
The  template  is  designed  to  assist  the  programming  staff  to  avhieve  a  better  structured 
and  better  documented  program  listing.    Furthermore,  program  module  interface  conditions 
can  be  generated  automatically  from  the  design  to  allow  better  control  and  better  implemen- 
tation. 

The  template  is  activated  by  the  programmer  at  the  time  when  the  program  is  to  be 
created.    It  will  ask  the  programmer  to  identify  the  program  and  program  module.  Basic 
information  concerning  the  program  module  will  then  be  obtained  automatically  from  the 
data  dictionary.    The  information  includes  the  following: 

Name  of  the  module. 

Specifications  of  the  module.    This  information  will  be  placed  as  the  sequences 
of  comment  statements  at  the  beginning  of  the  program  listing. 

Input  and  output  variables.    An  argument  list,  or  any  named  or  unnamed  COMMON 
block,  which  contains  the  variables  in  their  preselected  names  and  order, 
is  automatically  generated.    All  declarative  statements  necessary  to 
declare  the  input  and  output  variables  according  to  their  types  and 
initial  values  are  generated,    A  set  of  comment  statements  which  describe 
input  and  output  variables  is  also  generated. 

File  names  and  descriptions.    The  names  of  the  files  to  be  accessed  by  the 
module  and  their  file  descriptions  are  provided.    The  file  description  can 
be  obtained  from  the  file  description  module  in  the  data  dictionary. 

A  list  of  other  modules  called  by  this  module. 

A  list  of  references  which  indicates  where  the  design  documentations  of  the 
module  can  be  obtained.    The  design  specifications  of  the  module  may  be 
requested  by  the  programmer  from  the  data  dictionary.    This  includes  program 
structural  diagram  or  the  portion  of  the  diagram,  and  flow  diagram  of  the 
module.    The  descriptions  of  those  modules  which  are  called  by  this  module 
can  also  be  provided. 

The  programming  coding  template  automatically  sets  up  the  basic  structure  of  the  pro- 
gram listing.    Important  information  concerning  the  module  interface  are  provided 

automatically.    The  vital  module  interface  conditions  are  controlled  and  documented  by  the 
template  according  to  the  design. 

An  example  of  the  editing  process  is  illustrated  in  Figure  6. 


6.    ADVANTAGES  OF  USING  ADD 

The  use  of  ADD  has  several  advantages.    It  integrates  documentation  with  program  de- 
velopment activities  to  produce  better  designed,  structured,  and  documented  programs, 

6.1    Integration  of  Program  Design  and  Documentation  Activities 

The  use  of  ADD  insures  that  the  program  documentation  and  program  design  activities 
are  inseparable.    ADD  provides  a  structured  and  systematic  approach  to  design  and  implements 
the  program.    It  assists  the  designer  to  completely  specify  the  necessary  design  parameters. 
It  provides  an  automated  tool  for  the  designer  to  verify  and  to  refine  the  design.  It 
helps  the  designer  to  organize  the  design  works  and  to  document  the  final  design. 

ADD  provides  the  programming  staff  with  the  basic  program  structure  and  basic  design 
specifications  for  implementing  the  program.    The  important  program  module-to-module  inter- 
face conditions  are  generated  automatically  from  the  design.    Other  design  information  is 
referenced  and  documented  within  the  program  listing.    The  automatically  generated  program 
documents  provide  a  complete  set  of  design  specifications  which  can  be  used  as  "blueprints". 
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The  pre-selected  test  data  not  only  are  well  designed,  but  they  are  permanently  stored  for 
use  whenever  a  program  test  is  required. 


SUBROUTINE  QUADRT (A, B, C, RT, RTl , RT2, IMl , IM2, IND) 

***********************  it -k-kie  ** -k  ie  ie-k  *********  it -k  * -k** -tc-k  *  if -k  *****  * 

c 

C  FIND  ROOTS  OF  QUAURATIC  EQUATION 

C 

C  INPUT  VARIABLES  ARE  A,B,C.      THE  RESULTS  ^4AY  BE: 

C  1.    NO  ROOTS. 

C  2.    ONE  REAL  ROOT. 

C  3.    TWO  REAL  ROOTS. 

C  4.   TWO  COMPLEX  ROOTS. 

C 

Q**  *********************************************************  * 

c 

C  A     INPUT  VARIABLE 

C  B     INPUT  VARIABLE 

C  e     INPUT  VARIABLE 

C  RT     ROOT  OF  BX+C=0 

C  RTl     REAL  ROOT  ONE 

C  RT2     REAL  ROOT  TWO 

C  IMl      IMAGINARY  ONE 

C  IM2      IMAGINARY  TWO 

C  IND     RESULT  INDICATOR  CODING  SCHEME     0=NO  ROOT 

C  1=0NE  ROOT 

C-'  2=TWO  ROOTS 

C  3=COMPLEX 
C 

Q*  *********************************************************** 

REAL  A,B,C,RT,RTl,RT2,IMl, IM2 
INTEGER  IND 


THEN  statement 
ELSE  statement 

Figure  6.       Interactions  with  a 
Programming  Template. 
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Changes  to  program  modules  can  be  recorded  without  much  difficulty.    Updated  program 
documents  can  be  regenerated  at  any  time.    An  impact  analysis  can  be  quickly    and  auto- 
matically performed  during  program  maintenance.    For  Sample,  when  a  change  to  an  input  or 
output  variable  is  made,  a  scan  on  the  stored  information  in  the  data  dictionary  can  be 
activated,  and  all  those  modules  or  files  affected  can  easily  be  identified. 

6.2  Enforcement  of  Programming  and  Documentation  Standards 

ADD  helps  the  program  development  project  management  to  enforce  the  adopted  programming 
and  documentation  standards  and  conventions.    It  provides  a  means  to  establish  unified 
naming  conventions  for  assigning  variable    names,    and  names  for  files,  records,  and  program 
modules.    It  establishes  the  standards  for  program  documentation  and  program  listing.  It 
provides  a  basis  for  establishing  standard  testing  procedures. 

6.3  Automated  Program  Document  Generation 

ADD  can  generate  program  design  and  implementation  documents  automatically.    The  pro- 
gram document  updating  problem  is,  therefore,  reduced. 

6.4  Program  Validation 

ADD  provides  an  automated  means  for  validating  the  program  with  its  design.  During 
the  implementation  and  maintenance  stages,  any  difference  on  the  module  interface  condi- 
tions between  the  actual  implementation  and  the  design  can  be  detected  by  checking  the 
program  listing  with  the  design.    The  checking  can  be  automated.    The  designer  and  pro- 
grammer must  resolve  the  conflict  before  the  program  is  permitted  to  run.    The  pre- 
selected and  stored  test  data  along  with  the  program  specifications  is  another  means  to 
validate  the  program  implementation. 


7.  CONCLUSIONS 

ADD  integrates  the  program  design  and  program  documentation  activities.    This  approach 
not  only  helps  in  providing  better  documented  programs,  but  it  also  enhances  the  program 
design.    Program  design  and  implementation  documents  can  be  automatically  generated  without 
adding  additional  burdens  to  program  designer  and  programmer. 

The  programming  and  documentation  standards  can  be  better  enforced.    Structured  pro- 
gram design,  implementation,  testing,  and  documentation  can  be  easily  established.  The 
validity  of  the  program  can  be  better  verified. 

ADD  depends  on  the  availability  of  an  automated  data  dictionary  and  an  on-line  program 
editor.    Additional  software  is  necessary  to  generate  the  necessary  documents.    Software  is 
also  needed  to  assist  in  program  testing  and  to  verify  the  validity  of  the  implementation. 
Further  research  and  development  efforts  are  necessary  to  optimally  implement  the  proposed 
concepts  and  tool.    Detailed  design  and  implementation  of  ADD  are  scheduled  to  be  reported 
in  our  forthcoming  papers. 
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An  Approach  to  Computer  Maintained  Software  Documentation 

Bruce  I.  Blum 

The  Johns  Hopkins  University 
Baltimore,  Maryland  21205 

The  use  of  text  processors  to  manage  documentation  is  quite  common  in  data 
processing  facilities.    Consequently,  much  of  the  software  documentation  is 
produced  in  this  manner.    Unfortunately,  we  are  not  realizing  the  full  potential 
of  automation  in  the  production  of  the  documentation  required  for  the  different 
phases  of  the  life  cycle.    This  paper  shows  how  one  system  is  being  designed 
to  meet  the  documentation  needs  of  the  various  users  in  a  cost-effective  way. 
The  system  was  developed  for  a  specific  class  of  application  -  the  moderate 
sized  Information  Management  System  (IMS).    However,  the  approach  is  readily 
transportable  to  other  application  areas. 

Keywords:  Computer  maintained  documentation;  Documentation  requirements; 
Integrated  design  and  documentation. 

1.     IMS  DOCUMENTATION  REQUIREMENTS 

We  define  an  IMS  application  as  one  which  is  data  base  oriented,  uses  off-the-shelf 
hardware  and  software  systems,  has  no  real-time  demands  beyond  those  associated  with  user 
interaction,  and  is  limited  to  simple  control  logic  which  can  be  implemented  as  a  closed 
algorithm  or  a  decision  table.    A  moderate  sized  IMS  requires  from  1  to  20  man-years  of 
initial  development  and  has  a  useful  life  of  5  or  more  years.    Typical  IMS  applications 
have  more  than  one  class  of  user  in  an  organization;  most  commerical  and  medical  informa- 
tion systems  are  examples  of  this  type  of  system. 

Figure  1  illustrates  the  general  processing  flow  associated  with  the  development  of 
an  IMS.    The  Application  Environment  is  the  user's  "real  world."    The  implementation 
process  begins  with  the  formalization  of  the  system  requirements  in  the  Descriptive 
Environment.    The  functions  of  the  resultant  descriptions  are: 

•  To  feed  back  to  the  user  (sponsor)  what  the  system  is  to  do. 

•  To  supply  the  detailed  designer  a  set  of  specifications  which  he  can 
translate  to  an  implementable  solution. 

•  To  provide  a  foundation  for  the  final  system  documentation  required  by 
the  users,  e.g.,  operations  manual,  introductory  descriptions,  etc. 

As  segments  of  the  description  are  completed,  they  are  transformed  to  unambiguous 
specifications  in  the  Design  Environment  and  finally  an  executable  product  in  the 
Implementation  Environment.    The  latter  is  run  in  the  System  Operations  Environment.  Once 
the  system  becomes  operational,  the  design  and  implementation  details  are  of  little 
interest  to  the  user,  and  hence  their  documentation  is  not  shown.    Life  cycle  support  for 
a  completed  system  is  managed  by  a  process  called  system  maintenance.    Since  software  does 
not  wear  out,  system  maintenance  involves  (1)  correction  of  previously  undetected  errors 
and  (2)  expansion  or  modification  of  the  operational  system.    The  figure  shows  this  as  a 
feedback  loop  which  must  go  through  each  of  the  development  (and  documentation)  processes. 

Using  this  model  of  the  IMS  life  cycle,  five  users  of  the  system  documentation  can  be 
identified. 

•  Sponsor.    Requires  high  level,  descriptive  materials  which  define  the  key 
design  decisions  and  requirements  in  terms  of  the  Application  Environment. 
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SYSTEM  MAINTENANCE 


APPLICATION  ENVIRONMENT 


SYSTEM  USE 


DESCRIPTIVE 
ENVIRONMENT 


SYSTEM  DOCUMENTATION 


DESIGN 
ENVIRONMENT 


IMPLEMENTATION 
ENVIRONMENT 


SYSTEM  OPERATIONS  ENVIRONMENT 


DEVELOPMENT 


OPERATION 


Figure  1 

A  Model  of  the  System  Life  Cycle 

•  Designer.    Requires  materials  which  are  both  descriptive  and  highly  specific. 
His  documents  communicate  between  designer  and  sponsor,  designer  and 
programmer,  and  among  designers.    They  also  provide  a  history  and  reference 
to  be  used  by  the  author. 

•  Programmer.    Requires  highly  detailed  and  specific  information  which  will 
allow  the  translation  of  the  input  document  into  executable  code.    Note  that 
if  the  design  is  directly  translatable,  this  step  and  the  need  for  a 
programmer  (rather  than  designer)  is  eliminated. 

•  User.    The  needs  of  the  user  vary  according  to  the  user's  involvement  with 

the  system.    It  may  range  from  general  introductory  text  to  detailed  scenarios. 

•  Operator.    The  operators'  manual  will  vary  in  contents  according  to  the 
system;  it  is  always  required. 

Other  specialized  users  of  software  documents  are  involved  in  functions  such  as  system 
test  and  configuration  control.    For  clarity,  they  are  not  considered  here. 

Figure  2  presents  a  matrix  of  documentation  user  by  phase  in  the  development  life 
cycle.    This  paper  presents  a  document  development  philosophy  which  meets  the  different 
and  changing  needs  of  each  reader  in  a  cost-effective  manner. 
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AUDIENCE 

System  Phase  Sponsor     Designer     Programmer     User  Operator 

Preliminary  Design  v  x 

Design  XX  X 

Code/Test  X  X 

Operational  Use  XX  XX 

Maintenance*  XX  XXX 

*Maintenance  involves  all  of  the  above  steps. 


Figure  2 
Document  Requirements  Matrix 

2.    THE  TEDIUM  APPROACH  TO  SYSTEM  DEVELOPMENT 

TM 

The  Environment  for  Developing  Information  and  Utility  Machines  (TEDIUM    )  is  a  tool 
designed  to  implement  and  maintain  IMS  applications.    The  organization  and  philosophy  of 
TEDIUM  have  been  described  elsewhere  [1,2,3].    For  the  purposes  of  this  paper  it  will  be 
sufficient  to  familiarize  the  reader  with  some  key  characteristics  of  the  system. 

TEDIUM  provides  a  comprehensive  environment  for  the  development  of  an  IMS.    It  begins 
in  the  Descriptive  Environment  by  supporting  the  designer  in  (1)  the  documentation  of  the 
requirements  and  (2)  the  decomposition  of  the  requirements  into  a  data-process  flow  using 
structured  analysis  techniques.    An  example  of  how  this  is  done  is  illustrated  with  an 
appointment  system  example  [2]. 

Once  the  initial  design  documentation  is  available,  TEDIUM  provides  an  application 
oriented  specification  language  which  fully  defines  the  implemented  units,  i.e.,  the 
programs.    Three  types  of  specification  are  supported: 

•  Data  base  schema.    TEDIUM  uses  a  relational  model  with  relations  called 
"tables."    Each  table  is  decomposed  into  "index  elements"  and  "data  elements." 
All  elements  are  variable  length;  multiple  index  elements  are  allowed.  A 
special  data  type  called  text  manages  both  text  and  format  commands. 

•  General  formatting  rules.    Every  program  is  partially  defined  by  a  "frame" 
which  defines  the  formatting  rules  to  be  used,  e.g.,  is  this  an  interactive 
device,  what  should  the  heading  and  foot  lines  for  each  page  be,  etc. 

•  Specific  functional  descriptions.    Each  program  has  its  functionality  uniquely 
defined  by  a  program  specification.    Some  specifications  have  been  generalized 
(e.g.,  file  management  functions),  others  are  described  using  the  TEDIUM 
language. 

TEDIUM  generates  executable  programs  from  these  specifications.    Thus,  there  is  no 
traditional  programming  in  TEDIUM.    Design  and  implementation  involve  the  creation  of 
readable  specifications  which  establish  the  users'  requirements  and  the  detailed  processes 
to  satisfy  them. 

To  illustrate  how  TEDIUM  is  used  to  implement  an  IMS,  consider  a  hospital  locator 
system.    The  first  step  is  to  describe  the  requirements.    A  single  level  outline  of  the 
requirements  might  be: 


1.  Enter  Patients  into  the  Locator 

2.  Query  the  Locator  by  Location 

3.  Query  the  Locator  by  Patient 

4.  Discharge  a  Patient 

5.  Transfer  a  Patient 
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6.    Print  a  Midnight  Census 

After  further  analyses,  this  outline  is  modified  and  expanded.    Requirements  which  might 
not  be  initially  obvious  are  added  (e.g.,  maintain  a  dictionary  of  hospital  locations). 
Each  item  in  the  outline  is  then  described  in  text,  and  a  requirements  statement  is 
printed  for  sponsor  review. 

After  these  requirements  are  accepted,  the  designer  translates  the  requirements 
(what  is  to  be  done)  into  a  process-data  flow  design  (how  it  is  to  be  done).    Definition  of 
the  data  base  and  processes  is  done  in  parallel;  there  are  no  simple  maps  from  the  require- 
ments to  the  process  or  data  descriptions. 

The  definition  of  both  processes  and  data  groups  continues  by  using  the  same  outline 
approach.    The  process  outline  might  combine  requirements  1,  4  and  5  into  a  single  process 
called  Maintain  Locator  File.    A  single  level  outline  of  the  processes  might  be: 

1 .  User  Menu 

2.  Maintain  Locator  File 

3.  Display  Census  for  a  Location 

4.  Display  Patient  Location 

5.  Print  a  Midnight  Census 

The  single  level  outline  of  the  data  groups  might  be: 

1.  Locator  File 

2.  Patient  Index  to  Locator  File 

3.  Patient  Identification 

4.  Locator  Identification 

Again,  in  each  case  the  outline  is  expanded  and  descriptive  text  is  added.    The  audiences 
for  this  descriptive  text  are  both  the  sponsor  and  the  implementor/maintainor. 

Figure  3  shows  the  three  major  classes  of  documentation  text  and  the  links  among  them. 


REQUIREMENTS 


PROGRAMS  TABLES 

Figure  3 
TEDIUM  System  Definition  Tree 


113 


At  the  lowest  level,  the  processes  are  linked  to  the  programs  which  will  be  implemented; 
the  data  groups  are  linked  to  the  tables  (i.e.,  relations)  which  define  the  data  model. 
Each  program,  in  turn,  is  defined  as  a  Frame  (i.e.,  general  set  of  formatting  rules)  and  a 
minimal  specification.    The  minimal  specification  is  the  least  amount  of  information 
required  to  define  what  a  program  is  to  do.    These  specifications  average  14  lines  while 
the  programs  generated  from  them  are  5  to  20  times  longer  [1].    The  tables  are  defined  in 
a  schema  which  includes  a  data  dictionary.    Both  the  specification  and  schema  entries  have 
an  initial  block  of  descriptive  text  which  describes  their  function  or  purpose. 

Figure  4  contains  a  schema  for  the  LOCATE  table.    In  the  short  notation,  this  is 
LOCATE         PATIENT  LOCATOR 


This  table  serves  as  the  inpatient  locator.   It  is 
organized  bv  unit  and  contains  onlv  the  patients  who 
are  currently  in  the  hospital. 

INDEX  TERMS  : 

LOC  LOCATION  CHARACTER  <5) 

This  is  the  standard  hospital  unit  identifier. 
NAME  PATIENT  NAME  VARIABLE  LENGTH  (31) 


This  is   the  patient  name  in   the  form  lastffirst 
truncated  to  the  first  31  characters. 

HNO  HISTORY  NUMBER  CHARACTER  (7) 

PATTERN  7N 


This  is  the  standard  7  di^it  history  number, 


DATA  TERMS  : 

ADMDAT         ADMISSION  DATE  DATE  (8) 

ROLE  IN  TABLE  IS  DEFAULTED  TO  TODAY 


This  is  the  date  that  the  patient  was  admitted 
to  the  hospital. 

BED  BED  NUMBER  VARIABLE  LENGTH  (5) 

ROLE  IN  TABLE  IS  MANDATORY 

This  is  the  bed  number  within  a  hospital  unit. 

EDSDAT         ESITIMATED  DISCHARGE  DATE  DATE  <8) 

ROLE  IN  TABLE  IS  OPTIONAL 

This  is   the  estimated  date  for  patient  discharge. 
It  is  normally  modified  each  day  during   the  last  week 
of  stay  and  is  used  for  discharge  planning  and  census 
p  ro j  ec  ti  on  . 

Figure  4 
Sample  Table  Schema 
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written 


LOCATE ( LOC , NAME , HNO ) =ADMDAT , BED , EDSDAT 


Since  the  data  are  stored  in  alphabetical  index  order,  the  table  provides  an  index  by 
patient  name  for  each  hospital  location.    The  term  HNO  is  included  to  provide  uniqueness 
in  the  event  of  two  patients  with  the  same  name  in  the  same  unit.    (This  is  for  illustration 
only,  since  a  hospital  will  not  assign  patients  with  similar  names  to  the  same  unit). 

A  minimal  specification  for  the  program  to  admit  a  patient  (i.e.,  generate  an  entry 
in  LOCATE)  might  be: 


Input  LOC 

Call  SETHNO 

Input  ADMDAT 

Input  BED 

Input  EDSDAT 

Put  entry  in  LOCATE 


Input  is  a  command  which  prompts  for  the  element  using  its  dictionary  name  (e.g.,  "LOCATION" 
for  the  element  LOC),  checks  the  input  for  validity  and  stores  the  correct  data.    It  also 
accepts  the  "?"  as  a  help  prompt.    The  designer  may  supply  a  help  message;  the  default  is  a 
printing  of  the  data  dictionary  definition  as  shown  in  Figure  4.    The  program  SETHNO 
prompts  with  ENTER  NAME  OR  NUMBER,  processes  the  input,  adds  new  patients  to  the  patient 
identification  tables,  and  always  returns  with  NAME  and  HNO  set.    Put  writes  the  completed 
entry  into  the  data  base. 

The  process  of  design  and  implementation  with  TEDIUM,  therefore,  involves  the 
description  of  the  problem  in  a  structured  text  outline  followed  by  the  definition  of  the 
data  model  and  programs  with  the  TEDIUM  specification  tools.    Programs  are  generated  from 
these  specifications  and  tested  in  a  rapid  prototype  environment  [1].    All  text,  specifica- 
tions and  linking  information  are  available  online. 


3.    THE  TEDIUM  APPROACH  TO  DOCUMENTATION 


TEDIUM  is  a  set  of  programs  generated  by  TEDIUM.    Thus,  the  preparation  of 
documentation  for  an  application  is  seen  as  an  IMS  application.    All  requirements,  processes 
and  data  group  text  is  stored  as  tables  managed  by  the  TEDIUM  programs.    To  illustrate, 
the  requirements  are  stored  in  two  tables: 

REQ(REQID)=REQNM,REQTX 
REQL(REQID,REONO)=LREQID 

REQ  is  the  table  which  defines  the  requirement  text.    The  index  (REQID)  is  a  short, 
variable  length  identifier.    REQNM  is  the  requirement  name  and  REQTX  is  the  text  descrip- 
tion.   (The  text  data  type  calls  the  TEDIUM  text  processor  for  all  text  input  and  editing 
functions.)    For  example,  we  might  use 

REQID="ENTER" 

REQNM="ENTER  PATIENTS  INTO  THE  LOCATOR" 

REQTX="The  system  must  enter  patients  into  its  locator  file.    By  this  it  is 
meant  that  " 

Note  that  the  text  avoids  phrases  such  as  "the  system  shall."    This  allows  use  of  the 
requirements  text  in  a  wide  range  of  documents  throughout  the  life  cycle. 

The  second  table,  REQL,  establishes  a  tree  structure  for  the  requirements.    REQNO  is  a 
number  which  sequences  this  node  among  those  nodes  directly  linked  to  REQID.    LREQID  con- 
tains the  value  of  a  REQID  in  REQ.    For  example,  the  following  entries  in  REQL 

REQL( "ENTER", 10)= "ENTER. NEW" 
REQL( "ENTER" ,20)="ENTER. OLD" 

conform  to  the  outline 
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ENTER  PATIENTS  INTO  THE  LOCATOR 
NEW  PATIENTS 
RETURNING  PATIENTS 

The  links  between  text  groups  are  described  in  table  pairs  to  provide  bidirectional 
linkage.    For  example,  to  link  requirements  and  processes  we  use 

REQPRO(REQID,PROID) 
PROREQ(PROID,REQID) 

Links  to  the  schema  and  specifications  provide  access  to  their  text  documentation.  These 
are  defined  in 

TID(TID)=TNAME,TTX 
SID(SID)=SNAME,STX 
FID(FID)=FNAME,FTX 

for  tables,  specifications  and  frames  respectively.    The  element  NAME  is  a  30  character 
short  name,  and  TX  is  a  block  of  descriptive  text  which  describes  the  functionality  or 
use  of  the  item  identified.    Finally,  within  a  specification  there  are  links  to  the  optional 
help  text  (i.e.,  response  to  a  "?"  input). 

All  documentation  of  a  TEDIUM  application  is  created  from  this  data  base.    To  manage 
this,  one  additional  set  of  tables  is  defined  for  requirements,  processes  and  data  groups. 
For  requirements  it  is 

REQT(REQID,REQUS)=REQLV,REQFM 

where  REQUS  is  the  user  who  would  be  interested  in  this  block  of  text;  REQLV  is  a  level  of 
importance  with  1  being  the  greatest  and  10  indicating  details  of  little  general  interest; 
and  REQFM  contains  formatting  instructions  such  as  eject  a  page,  do  not  print  the  heading, 
follow  with  the  full  tree  for  this  node,  etc. 

With  this  table,  one  can  now  create  documents.    For  example,  a  system  overview  might 

be: 

Print  all  requirements  with  REQUS= "general "  and  REQLV  less  than  3. 

A  Users'  Manual  for  the  patient  locator  function  as  one  application  in  a  total  hospital 
information  system  might  be: 

Print  a  title  page  with  "Users'  Manual,  Patient  Locator  Functions" 

Print  "Introduction"  as  all  requirements  with  REQUS="general "  and  REQLV=1 

Print  "The  Patient  Locator"  as  all  requirements  in  the  "LOCATE"  tree  with 
REQUS="general "  or  "user"  and  REQLV  between  2  and  5 

Print  "General  Instructions"  as  all  processes  in  the  tree  "GEN"  (This  is  a 

general  set  of  instructions  for  the  use  of  all  TEDIUM  generated  systems.) 

Print  "Locator  Flow"  as  processes  in  the  tree  "LOCATE"  with  PROUS= "general " 
or  "user. " 

Print  "Data  Dictionary"  and  print  outline  of  "LOCATE"  data  groups  with  linked 
tables.    Follow  with  an  appendix  containing  all  the  table  schema. 

The  same  document  may  be  described  more  briefly  as:  User  Manual  for  "Patient  Locator 
Functions"  using  requirement  node  "LOCATE,"  process  node  "LOCATE"  and  data  group  "LOCATE." 

A  final  level  of  detail  can  be  produced  for  the  users'  manual  by  processing  the 
specification  and  its  help  messages.    For  example,  the  program  to  enter  a  patient  might  be 
documented  by: 
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(Lead  in  text  from  the  process  tree) 
"The  system  will  now  prompt: 

LOCATION" 
(Help  message  text) 
"The  system  next  prompts 

ENTER  NAME  OR  NUMBER" 
(Help  message  text  from  program  GETHNO) 


Each  of  the  above  documents  is  directed  to  users  and  designers.    The  availability  of 
all  text  and  specifications  in  a  data  base  also  provides  an  information  resource  for  those 
responsible  for  the  implementation  and  maintenance  of  the  application.    TEDIUM  supports 
online  (and  printed)  access  to  the  following: 

•  Text  data  by  node  or  tree 

•  Table  definition  and  the  data  dictionary 

•  Specifications  for  programs  and  frames 

•  Cross-reference  of  data  element  by  table  and  use  (index/data) 

•  Cross-reference  of  programs  (calls/called  by) 

•  Cross-reference  of  programs  with  tables  and  vice  versa  (reads/writes) 

•  Hierarchical  relationships  among  programs  (a  tree  structure  showing  how 

programs  are  called.) 

Since  all  of  these  outputs  are  generated  directly  from  the  data  base,  they  always  accurately 
reflect  the  current  application  design. 

4.  CONCLUSION 

This  paper  has  briefly  (1)  presented  a  model  which  describes  the  kinds  of  documentation 
required  for  an  information  management  system,  (2)  shown  how  the  text  and  specifications  for 
such  an  application  can  be  managed  in  the  design  environment,  and  (3)  illustrated  how  the 
resultant  design  data  base  can  create  the  necessary  formal  system  documentation. 

Two  types  of  documentation  were  identified:  (1)  material  to  be  distributed  to  sponsors 
and  users  and  (2)  design  information  required  for  implementation  and  maintenance.  The 
former  is  always  printed;  the  latter  is  always  available  online.    The  computer  stored  data 
base  is  the  primary  source  and  reflects  the  most  current  documentation.    Given  the  proper 
discipline  for  configuration  control,  changes  to  the  system  will  be  entered  into  the 
documentation,  and  updated  documents  can  be  created  with  minimal  effort.    Since  the  lower 
level,  implementation  oriented  documentation  is  derived  directly  from  the  specifications, 
it  will  always  accurately  reflect  the  current  design. 

The  system  discussed  (TEDIUM)  has  been  in  operational  use  for  about  a  year  in  a  MUMPS 
prototype.    The  main  thrust  in  its  use  has  been  rapid  prototyping  and  system  development. 
It  provides  the  work  environment  for  a  group  of  ten  programmers.    Several  major  systems 
which  have  been  developed  or  converted  with  TEDIUM  are  now  in  operational  use  [4,5].  The 
documentation  for  these  systems  is  being  managed  as  described  above. 

Still,  some  disclaimers  are  in  order.    TED-IUM  is  not  yet  available  for  export.  The 
approach  to  documentation  is  in  a  trial  stage,  and  we  are  learning.    Only  a  limited  class 
of  applications  is  being  considered,  and  the  problems  of  multiple  versions  and  releases 
have  not  been  addressed.    Nevertheless,  we  are  convinced  that  the  concepts  presented  offer 
an  integrated,  workable  methodology  for  inexpensively  eliminating  that  ever  present 
problem:  missing  or  inaccurate  documentation. 
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Automated  and  Automatic  Documentation 
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Software  documentation  standards  should  reflect  the  evolution  of  software 
engineering.    Moreover,  future  progress  In  software  development  should  be 
expected  and  allowance  for  progress  should  be  Incorporated  In  documentation 
guidelines . 

Systems  such  as  the  Automated  Documentation  System  may  serve  as  prototypes 
for  producing  automated  documentation.    Both  Increased  productivity  and  cost 
savings  can  be  expected  from  requiring  meaningful  documentation. 

Kej^ords:  automated  documentation;  documentation  standards;  Internal 
documentation;  software  engineering; 

1.  INTRODUCTION 

During  a  recent  review  of  documentation  standards  ([1],   [2],   [6]),  two  deficiencies 
seemed  apparent:   1)  the  documentation  requirements  have  little  relevancy  to  scientific  and 
engineering  software  development  efforts;  2)  software  engineering  has  evolved  beyond  scope 
of  current  standards.     These  two  deficiencies  result  in  loss  of  programmer  productivity,  in 
increased  code  rewriting  —  in  general,  in  decreased  cost  benefits  of  the  software.  This 
paper  will  examine  these  two  deficiencies  and  propose  possible  solutions. 

2.  SUMMARY  RECOMMENDATIONS 

This  paper  recommends  creation  of  'flexible'  documentation  standards.    Because  of  the 
rapid  evolution  of  software  engineering,  current  procedures  and  practices  may  have  an 
effective  lifetime  of  less  than  five  years.     Improved  productivity  can  result  when  the 
programmer  views  the  documentation  standard  as  effective  and  useful. 

This  paper  further  recommends  automation  of  the  software  documentation,  whether  from 
well  commented  code  or  from  text  editing  processors.    This  machine-readable  documentation 
should  form  part  of  the  complete  software  package.    The  preceding  actions  can  result  in 
Increased  productivity  by  allowing  the  programmer  to  document  and  update  on  the  same 
hardware.     If  the  major  portion  of  the  documentation  is  contained  within  the  source  code, 
then  many  kinds  of  documentation  reports  may  be  automatically  generated. 

In  general,  substantial  cost  savings  —  particularly  labor  costs  —  can  result  from 
adoption  of  these  recommendations:  programmer  productivity  increases  may  result  from 
Improved  motivation;  effective  software  life  may  be  extended. 
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3.     DEFINING  THE  PROBLEM 


1)  The  documentation  requirements  have  little  relevancy  to  the  actual  workings  of 
engineering  software.     It  seems  obvious  that  documentation  should  aid  the  understanding  of 
the  software  and  how  the  software  operates.    Most  documentation  standards  seem  to  require 
only  superficial  details  —  file  names,  record  layouts,  etc.     ([1],    [2],    [6])  These 
requirements  may  be  applicable  to  typical  batch  oriented  COBOL  environments  used  in  most 
financial  and  business  applications,  but  do  not  apply  to  some  of  the  Fortran  environments 
used  in  scientific  and  engineering  applications.     Further,  the  documentation  standards  do 
not  easily  lend  themselves  to  detailed  explanations  of  complicated  software. 

What  are  the  'record  layouts'  in  a  system  where  graphic  input  (e.g.  joystick, 
digitizer,  light  pen)  are  used?    Likewise,  how  does  one  describe  'record  layouts'  for 
English-like  language  interfaces  processed  using  formal  grammars?     Even  though  these  kinds 
of  systems  may  not  presently  form  a  majority  of  the  software  developments,  these  kinds  of 
systems  (interactive,  graphic  input,  user-friendly  interfaces)  are  the  trend  of  the 
immediate  future. 

Vlhen  trying  to  document  one  of  these  systems  according  to  the  standards,  programmers 
become  discouraged  when  the  specifications  don't  appear  to  apply.     Perhaps  some  recognition 
of  these  kinds  of  systems  (e.g.     interactive,  flexible  input  requirements,  etc.)    would  aid 
usage  of  the  documentation  standards.    Also,  recognizing  that  software  requirements  do 
evolve  would  enhance  documentation  standards. 

2)  Software  engineering  has  evolved  beyond  the  scope  of  the  standards.     This  statement 
is  true  regardless  of  the  language  —  COBOL  or  Fortran.     Current  software  is  being 
developed  and  used  on  multi-programming,  often  interactive  hardware.  User-friendly 
interfaces  are  being  required.     Thus,  the  standard  documentation  requirements  of  frequency 
of  runs  seem  useless.     Frequency  of  runs  —  anytime  the  user  wishes  —  are  not  as 
important  as  when  these  frequencies  were  required  for  computer  resource  scheduling. 

Superficial  knowledge  of  the  software  may  be  sufficient  after  the  software  is  placed 
into  production,  but  the  software  development  manager,  as  well  as  the  software  maintenance 
programmer,  needs  far  more  detailed  knowledge  about  the  actual  code.     Comments  placed  into 
well  written  code  (internal  documentation)  will  aid  the  maintenance  programmer  as  well  as  a 
development  manager.     To  enhance  productivity,  it  would  be  nice  if  these  well  commented 
routines  could  be  used  to  satisfy  post-implementation  documentation  requirements. 

As  the  evolution  of  software  engineering  progresses,  the  manager  and  user  are  becoming 
more  cost-accountable  (i.e.     like  other  departments).     Software  development  is  being 
scrutinized  for  cost  benefit,  timeliness,  and  effective  life.     Users,  likewise,  are 
becoming  more  sophisticated  both  in  specifying  reasonable  desires  and  in  recognizing  usable 
software  products.     Thus,  more  importance  is  being  attached  to  management  and  user 
knowledge  of  developing  software;  managers  and  users  also  need  to  know  what  the  code  does 
—  though  not  necessarily  at  a  detailed  level. 

Internal  documentation  —  well  commented  code  —  can  solve  most  of  these  requirements; 
external  documents  need  only  be  used  for  overviews  and  more  detailed  descriptions.  If 
internal  documentation  can  be  used  to  produce  readable  documents,  comments  will  be 
considered  almost  automatic  documentation. 

Originally,  scientific  processors  were  merely  number  crunchers;  text  processing  — 
user  manuals,  documentation,  etc.     —  was  written/dictated  by  programmers  and  then  typed. 
Typing  has  since  turned  into  word  processing,  typically  on  different  hardware  than  used  for 
software  development.     This  divergent  hardware  seems  less  necessary  now  that  most 
scientific  processors  have  good  text  editors  and  text  processing  programs. 

Rather  than  the  redundancy  of  having  software  documentation  on  separate  hardware,  it 
would  be  cost  beneficial  to  have  the  programmer  produce  the  documentation  on  the 
development  hardware  —  ideally,   internal  to  the  code  itself. 
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A.     POSSIBLE  SOLUTIONS 


4.1    Usable  and  Automated  Documentation 


Any  possible  solutions  must  emphasize  'usable'  documentation.     These  solutions  must 
also  be  cost  beneficial  —  or  they  won't  be  enforced.     The  documentation  audience  — 
manager,  user,  and  maintanence  programmer  —  should  be  satisfied  with  the  result.  Many 
problems  can  be  avoided  by  the  use  of  structured  programming  enhanced  with  mnemonic 
variable  name  usage.     Structured  programming  will  help  produce  good  code  because  of  its 
emphasis  on  modular  design.     Guidance  has  begun  to  appear  for  using  structured  progranming 
[3]. 

Automated  production  of  documentation  reports  will  also  help,  particularly  if  these 
reports  can  be  produced  directly  from  the  source  code(s).     Then,  new  reports  can  easily  be 
produced  whenever  changes  occur  in  the  code.    Also,  the  documentation  will  then  be  wherever 
the  source  code  is  found.     This  automation  seems  most  easily  done  by  commenting  code; 
external  documentation  can  focus  on  less  changeable  items  of  the  software  —  purpose, 
overall  techniques. 


4.2    The  Automated  Documentation  System 

Rather  than  theorizing  about  such  a  system,  I  can  tell  you  about  one  that  already 
exists.     The  Automated  Documentation  System  (ADS)    [4]  was  developed  at  the  Construction 
Engineering  Research  Laboratory  (CERL)  to  provide  high  quality  documentation  of  Fortran 
source  code(s). 

The  Automated  Documentation  System  (ADS)  is  a  computer  program  and  user  procedure 
designed  to  facilitate  management  of  the  development  of  software  and  the  production  of 
final  documentation  for  Fortran  programs.     The  ADS  system  can  be  used  in  two  ways.     1)  At 
any  point  during  development  of  the  software,  the  status  of  the  development  process  can  be 
determined  by  the  application  of  the  ADS  program  to  the  source  code  under  development. 
Flow  charts  and  internal  documentation  are  summarized  for  the  project  manager.     2)  After 
the  software  is  complete,  external  documentation  can  be  produced  from  the  internal 
documentation  by  running  the  ADS  program. 

The  ADS  program  is  written  in  Control  Data  Corporation  (CDC)  Fortran  extended,  and  can 
be  used  on  CDC  6000/7000/170  series  computers  with  few  or  no  modifications.     The  source 
code  is  non-proprietary. 

The  Automated  Documentation  System  (ADS)  can  be  viewed  as  a  prototype  of  the  necessary 
systems  for  obtaining  good  documentation.     Similar  methods  could  be  used  for  COBOL,  Pascal, 
ADA,  and  other  languages.    ADS  relies  on  special  comments  placed  into  the  Fortran  source, 
stores  these  comments  along  with  other,  compiler  provided  information  on  software  data 
files,  and  retrieves  and  reformats  this  information  from  these  files  for  specialized 
reports.     The  ADS  user  —  programmer  —  can  choose  from  20  different  sections  for 
documenting  his  code  (e.g.     PURPOSE,  METHOD,  VARIABLE  DICTIONARY,  FLOW,  etc.).  Compiler 
supplied  information  includes  number  of  lines  of  code,  routines  used  by  a  routine, 
variables  and  their  types,  etc. 

The  software  project  manager  can  specify  which  sections  are  to  be  used  in  a  developing 
software  system.     When  top  down  design  is  employed,  a  system  similar  to  the  ADS  Stub 
Generator  [5]  can  be  used  to  enforce  the  manager's  requirement.     However,  meaningful 
documentation  —  the  documentation  accurately  representing  the  purpose  of  the  software  — 
implies  a  careful  review  process.     Thus,  the  reviewer  (manager  or  user)  needs  to  check  the 
documentation  for  meeting  the  'standards'  requirements  and  to  review  the  documentation  for 
content . 
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An  example  application  of  ADS  to  the  ADS  main  program  can  be  viewed  in  Figure  1. 
LOGICAL  FLOW. 

CALL  INITIALIZATION  ROUTINES   (ADINIT,  FHINIT,  PINIT) 
WHILE  NOT  EOF(REFFL)  DO   [SOURCE  CODE  PROCESSING] 

PROCESS  REFERENCE  MAP  FOR  A  ROUTINE 

SCAN  SOURCE  CODE  FOR  CURRENT  ROUTINE 

PROCESS  DOCUMENTATION  FOR  CURRENT  ROUTINE 
END   [SOURCE  CODE  PROCESSING] 

PERFORM  USER  INPUT  COtlMANDS    [TITLE,   PRINT,  DRAW,  ETC.] 
PERFORM  END -OF- JOB  PROCESSING 

FILES  USED  IN  ADSDOC     ARE  ~ 
DEBUG  INPUT  INVBK  INVFL  MASBK  MASFL 

OUTPUT         REFFL  RPTOUT         SRCFL  TIMES 

THIS  MAIN  PROGRAM  HAS  APPROXIMATELY  112  NON-COMMENT  LINES. 

IT  WAS  WRITTEN  IN  FORTRAN  66. 


Figure  1.     Excerpt  of  ADS  documentation. 

ADS  Reports  can  be  retrieved  for  any  combination  of  sections,  routines,  and  common 
blocks.     These  reports  can  be  read  by  anyone,  if  the  comments  are  meaningful;  no  one  will 
have  to  sift  through  the  Fortran  code  to  understand  the  software.     These  reports  can  be 
produced  at  any  point  in  the  software  development  and  can  provide  the  manager  and  user  with 
crucial  information  about  development  progress.     Several  kinds  of  reports  currently  exist 
in  the  system  —  reports  of  documented  ADS  sections  for  routines,  reports  of  documented  ADS 
sections  for  common  blocks,  and  a  'tree  report'  —  static  calling  structure  from  any 
specified  'root'  module. 


4.3    ADS  Examples 

Though  space  limitations  do  not  allow  complete  examples  of  ADS  outputs  to  be  shown, 
some  excerpts  from  ADS  inputs  and  outputs  may  be  useful.     The  retrieval  user  communicates 
with  the  ADS  program  using  simple  English-like  commands: 

TITLE  SOFTWARE  IN  PROGRESS; 

REPORT  IGUIDE=TITLE, PURPOSE, USAGE, FORMAL  PARAMETERS; 
PRINT  NARROW  (IGUIDE)  FOR  ALL  ROUTINES; 
DRAW  TREE; 
END; 


The  Automated  Documentation  System  program  places  information  on  the  documentation 

files  from  the  TITLE  and  REPORT  command.     It  retrieves  the  necessary  documentation  records 

for  the  PRINT  command;  and  it  draws  the  static  calling  structure  of  all  main  programs  in 
this  example  DRAW  command. 

Again,  the  programmer  places  special  comment  cards  into  the  Fortran  source  code. 
These  comment  cards,   together  with  the  information  provided  by  the  Fortran  compiler 
reference  map,  create  the  documentation  record.     For  an  example  of  ADS  output  produced  by 
the  compiler  reference  maps,  refer  to  Figure  2. 
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ROUTINES  CALLED  BY  AVGR        ARE  ~ 
TRACER 

INTRINSIC  FUNCTIONS  CALLED  BY  AVGR        ARE  ~ 

lABS 

COMMON  BLOCKS  CALLED  BY  AVGR        ARE  ~ 
DEBUGR        SUMCOM        COMMAR  COMMDEF 

THE  ROUTINES  WHICH  CALL  AVGR  ARE  — 

PRNTSUM 


Figure  2.     Fortran  Reference  Map  produced  documentation. 

For  an  example  of  typical  ADS  output  produced  from  the  special  comment  cards,  refer  to 
Figure  3.     Tree  reports  may  be  'drawn'  starting  at  any  module  and  continuing  for  a  user 
specified  depth.    An  example  of  the  two  top  levels  of  ADS  itself  can  be  viewed  in  Figure  4. 

TITLE . 

AVGR  -  AVERAGING  ROUTINE 
PURPOSE. 

AVGR  CALCULATES  AN  AVERAGE  AT  THE  REQUESTED  REPORT  FREQUENCY  (INTERMITTANT  AVERAGE) 
OR  A  GRAND  AVERAGE  AT  THE  REQUESTED  REPORT  FREQUENCY+1   (I.E.,  DAILY  FOR  AN  HOURLY 
REPORT)  BASED  ON  THE  INPUT  CODE,  AND  ZEROES  OUT  THE  APPROPRIATE  INTERNAL  SUM  BUFFER. 

USAGE. 

CALL  AVGR(CODE,VARTYP, BUFFER, LTH) 
ENVIRONMENT  — 

THE  INTERNAL  FLAGS  DESIGNATING  WHICH  ARITHMETIC  OPERATIONS  ARE  ALLOWED  ON  EACH 
VARIABLE  MUST  BE  SET  PRIOR  TO  A  CALL  TO  AVGR. 

IF  THE  REPORT  WRITER  LANGUAGE  AND  PARSER  ARE  USED  ALL  OPERATIONS  ARE  ALLOWED  ON 
ALL  VARIABLES  INPUT.     THE  VARIABLES  AND  THEIR  ALLOWABLE  OPERATIONS  MAY 
ALTERNATELY  BE  SET  WITH  A  CALL  TO  INITV. 

THE  INPUT  DATA  BUFFER  MUST  ALSO  BE  FILLED  WITH  HOURLY  DATA  AND /OR  'SPECIAL'  OR 
'NODATA'  FLAGS  FOR  EACH  VARIABLE  REQUESTED  FOR  THE  CURRENT  REPORT  BEFORE  EACH  CALL. 
THIS  IS  ACCOMPLISHED  BY  A  CALL  TO  'SETID'  FOR  EACH  USER-SPECIFIED  ZONE,  SYSTEM  OR 
PLANT  NUMBER  (ID)   IN  THE  REPORT  THAT  REQUESTS  RPTFLE  DATA,  AND  BY  A  CALL  TO 
'RDFILES'  EACH  HOUR  TO  RETRIEVE  THE  DATA  FOR  ALL  REQUESTED  VARIABLES. 

VARIABLE  DICTIONARY  FOR  ROUTINE  AVGR 

FORMAL  PARAMETERS. 

BUFFER    -  1-DIMENSIONAL  ARRAY  IN  WHICH  RESULTS  OF  AVERAGE  ARE  RETURNED. 

CODE        -  ACTION  CODE  FOR  AVERAGING  (NEGATIVE  CODES  ALSO  ZERO  BUFFER) 

1=  PERFORM  AN  INTERMITTANT  AVERAGE,   STORE  RESULT  IN  INTERNAL  BUFFER 
2=  PERFORM  A  GRAND  AVERAGE,  STORE  RESULT  IN  INTERNAL  BUFFER 
-1=  RETURN  CURRENT  INTERMITTANT  AVERAGE  FROM  INTERNAL  BUFFER 
-2=  RETURN  CURRENT  GRAND  A\?ERAGE  FROM  INTERNAL  BUFFER 

LTH  -  LENGTH  OF  BUFFER 

VARTYP     -  RECORD  TYPE  OF  DATA  TO  BE  AVERAGED 

(1=Z0NE,   2=SYSTEM,  3=PLANT,  4=SYSTEM  ZONE) 

Figure  3.     Comment  produced  documentation 
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To  ensure  meaningful  documentation,  these  reports  are  used  in  structured  walk-thrus  of 
code  and  in  meetings  with  users  and  managers.     Reviewing  this  documentation  for  compliance 
with  development  standards  and  for  completeness  of  meaning  becomes  the  responsibility  of 
the  managers  and  users.     Using  these  reports  also  eliminates  the  tendency  of  programmers  to 
say  'the  code  is  self-documenting'.     Of  course,  these  reports  cannot  substitute  for  code, 
but  they  do  provide  a  common  ground  for  discussions,  changes,  etc.     When  implementing 
changes,  the  programmer  need  only  update  the  routines /common  blocks  changed,  and  rerun  ADS; 
software  documentation  files  will  be  updated  to  reflect  the  changes. 

ADSDOC  

|_ADINIT 

|_DTFTN  

I  |_RDCDC4 

I  |_RDCDC5 

I  |_RDLINE 

i_FHEND 

|_FHINIT 

|_PINIT 

|_PREPARS_ 

I  |_CDPARS 

|_RPTMON  

|_DELCMD 
|_DRACMD 
|_HELCMD 
|_PRTCMD 
|_RPTCMD 
I  TITCMD 


Figure  4.     A  TREE  report  showing  user  specified  depth. 

Certain  documentation  reports  may  not  easily  fit  into  the  'internal'  comment 
structure.     These  kinds  of  reports  usually  deal  with  overall  views  of  the  software  or 
intricate  interactions  of  several  routines,  programs,  etc.     For  these  cases,  one  can  still 
produce  the  document  in  machine-readable  form  using  a  text  processor  and  carry  these 
documents  as  part  of  the  software.     Thus,  all  the  available  documentation  about  the 
software  would  be  available  as  one  package. 


4.4    Automated  Documentation  System  Usage 


The  Construction  Engineering  Research  Laboratory  developed  the  Automated  Documentation 
System  to  meet  documentation  needs  of  users.    ADS  has  been  used  in  several  systems  produced 
at  the  Construction  Engineering  Research  Laboratory  since  December  1978.  Retrofit 
documentation  of  several  large  systems  has  also  been  accomplished  using  the  special 
comments  required  by  ADS.     In  particular,  the  Building  Loads  Analysis  and  System 
Thermodynamics  (BLAST)  program  —  approximately  100,000  lines  of  Fortran  source  code  — 
that  has  been  installed  on  40  different  sites  uses  the  ADS  commenting  system.  Producing 
the  documentation  for  BLAST,  then,  is  merely  a  matter  of  executing  the  ADS  program  against 
the  BLAST  documentation  files.     In  the  case  of  the  BLAST  system,  ADS  is  being  used 
primarily  in  program  maintenance. 

However,  several  other  users  of  ADS  at  CERL  have  been  using  the  ADS  system  primarily 
as  a  system  development  tool.     These  users  have  found  the  automated  reports  will  help  them 
identify  mis-typed  variable  names,  as  well  as  provide  indications  of  module  completeness. 
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4.5    Status  of  the  Automated  Documentation  System  (ADS) 

The  ADS  system  periodically  undergoes  some  revision  primarily  to  respond  to  new  needs 
of  its  users.     The  system  is  somewhat  prototype  (though  used  productively)  since  the  code 
exists  primarily  for  Fortran  and  on  Control  Data  Corporation  hardware. 

Moving  ADS  to  new  hardware  requires  some  code  revisions  and  creating  reference  map 
decoding  routines  for  the  new  hardware's  Fortran  compiler.     Obviously,  a  portable  Fortran 
code  scanner  that  produces  the  kind  of  information  used  by  ADS  (e.g.     externals,  intrinsic 
functions,  variable-common  mapping)  would  aid  conversion  to  new  hardware. 

Using  ADS  for  languages  other  than  Fortran  would  be  more  difficult.     For  example,  many 
of  the  terms  used  in  ADS  are  not  applicable  to  COBOL  (e.g.     lack  of  common  blocks, 
subroutines  not  widely  used).     However,  the  basic  concept  of  ADS  —  storing  documentation 
on  files  for  later  retrieval  —  could  be  applied  to  many  source  languages. 

5.  CONCLUSION 

Documentation  standards  must  be  applied  to  a  wide  variety  of  software  systems. 
Originally,  software  was  used  in  batch  oriented,  single  programming  environments.  However, 
present  and  future  software  will  be  used  in  interactive,  multi-programming  environments. 
Thus,  any  documentation  standard  must  be  flexible  in  its  requirements. 

The  need  for  meaningful  documentation  exists  throughout  the  software  life  cycle. 
Software  development  managers  need  to  be  able  to  easily  assess  the  progress  of  development. 
Users  need  to  be  able  to  assure  themselves  that  they  are  getting  the  product  that  meets 
their  needs  or  desires.    Maintanence  programmers  need  to  have  system  documentation  readily 
available  and  easily  revisable. 

The  Automated  Documentation  System  (ADS)  system  was  developed  to  meet  these  needs  at  a 
specific  installation  (the  Construction  Engineering  Research  Laboratory  —  CERL).  Tools 
like  ADS  may  also  meet  the  needs  of  the  documentation  standards  community. 
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SESSION  C:  Discussion 


H.  Hecht 


SoHaR,  Incorporated 


Currently  available  tools  permit  partial  automation  of  document 
generation.  Thereby,  they  reduce  cost  and  schedule,  provide  standardization 
of  format,  and  improve  the  quality  of  the  resulting  product.  Tools  can  help 
in  three  areas  of  document  preparation:  collecting  information,  establishing 
the  format,  and  in  presentation  to  the  user.  The  authors  of  this  session 
covered  all  three  areas  as  is  shown  in  the  following  table. 


DOCUMENTATION  AREAS  SERVED  BY  TOOLS 


AREA 

Information 
Content 

Format 


EXAMPLES 

Variables  dictionary,  program  flow,  etc. 
Copies  of  actual  program  use 

Pre-arranged  sequence  of  topics 

Mandatory  declarations 


Presentation     Screen  format 

Text  editing  and  formatting 


AUTHOR 

Lawr ie 
Henry 

Ting 
Lawr  ie 
Malhotra 
Blum 

Ting 
Henry 


The  authors  recognized  limitations  of  current  use  and  the  methodology 
associated  with  their  use,  including: 

*  Difficulties  in  devising  tools  for  general  purpose  documentation.     The  most 

successful  tools  were  dedicated  to  a  single  application  area. 

*  The  full  benefit    of     tools     can     be     realized    only     if     there     is  strong 

management  support  and  follov/-up. 

*  Current  methods  address  primarily  user  and  maintenance  manuals. 

Looking  into  the  future,  one  may  expect  greater  emphasis  on  interactive 
documentation.  Menu-driven  input,  supplemented  by  HELP  routines,  is  already 
widely  used  and  reduces  the  dependence  on  user  manuals.  Screen  presentation 
of  fully  documented  source  code,  possibly  structured  at  several  levels  of 
detail,  may  supplant  much  of  the  material  currently  included  in  maintenance 
manuals.  Techniques  that  permit  simultaneous  interactive  display  of  programs 
and  associated  data  structures  promise  to  be  particularly  helpful  for  program 
development  and  maintenance. 

A  hopeful  sign  is  that  the  academic  community  may  be  taking  some 
interest  in  documentation  as  evidenced  by  Ting's  paper.  That  paper 
recognizes  that  there  is  a  close  relation  between  good  program  design  readily 
understood  documentation.  This  emphasizes  that  documents  prepared  for  human 
understanding  and  programs  prepared  for  use  in  the  computer  are  complementary 
representations  of  the  same  information  processing  activities.  Deficiencies 
in  either  one  will  usually  degrade  the  other. 
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Session  Summary:    Tools  for  Improved  Documentation 


Sheila  E.  Frankel 


National  Bureau  of  Standards 
Gaithersburg,  Maryland 


This  session  proposed  the  use  of  software  tools  in  documentation  development  as  a 
promising  solution  to  some  of  the  problems  plaguing  traditional  program  documentation- 
expense,  limited  usefulness  of  the  final  product,  and  the  problem  of  keeping  the  documenta- 
tion current  as  the  project  changes.    It  was  agreed  that  part  of  the  problem  is  that  docu- 
mentation is  developed  and  maintained  separately  from  the  program.    This  is  the  case  whether 
it  is  written  in  parallel  with  program  development  or  whether  it  is  done  as  a  follow-up 
effort. 


Linda  Lawrie  suggested  another  problem— that  documentation  standards  and  methods  have 
remained  static,  while  the  technology  of  program  development,  or  software  engineering,  is 
constantly  changing  and  evolving. 


One  =»pproach  to  help  mitigate  these  problems  is  the  use  of  automated  documentation 
tools.    Tnese  tools  can  make  the  development  of  documentation  part  and  parcel  of  the  pro- 
gramming development  process.    Several  different  approaches  to  the  use  of  tools  have  been 
suggested. 


Ashok  Malhotra's  approach  is  the  development  of  a  high-level  programming  language  that 
is  easy  to  understand  and,  thus,  self-documenting.    In  the  EAS-E  system,  by  integrating  this 
language  with  a  DBMS,  a  new  entity  has  been  created — executable  documentation. 


T.  C.  Ting's  ADD  system  integrates  program  design  and  documentation.    It  imposes  order 
on  the  design  documentation  through  the  use  of  a  template.    This  information,  together  with 
pseudo-code  and  test  data,  is  used  to  create  structure  charts  and  flow  diagrams,  which  in 
turn  can  be  used  in  the  program  development  and  validation. 


Bruce  Blum  has  suggested  reversing  the  customary  process  of  developing  Information 
Management  Systems.    His  TEDIUM  system  allows  the  developer  to  specify  system  requirements 
in  terms  of  format,  function  and  processes,  and  from  these  executable  programs  are  generated. 


Linda  Lawrie  follows  the  customary  procedure  of  program  development,  but,  in  her  ADS 
system,  the  documentation  is  either  contained  within  the  program  or  automatically  generated 
through  program  analysis. 


Ray  Houghton  presented  the  idea  of  including  different  types  and  levels  of  on-line  doc- 
umentation in  an  interactive  program.    He  used  as  an  example  a  system  developed  by  Nathan 
Relies  and  Lynne  Price  that  was  demonstrated  at  a  recent  tool  fair  co-sponsored  by  NBS  (See 
NBS  Special  Publication  500-80).    This  system  enables  the  user  to  specify  precisely  the 
information  and  the  level  of  detail  he  needs,  and  not  to  be  distracted  by  receiving  too  much 
or  too  little  information  in  response. 
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Lee  Henry  suggested  that,  once  the  documentation  effort  is  integrated  into  the  softwar 
development  process,  not  only  do  we  need  standards  for  the  contents  of  documentation,  but 
for  the  processes  and  procedures  of  documentation  development  as  well.    She  also  suggested, 
as  an  addition  to  the  program  development  team,  a  documentation  specialist,  who  would  be 
involved  in  all  aspects  of  the  software  design. 


These  systems  represent  differing  views  of  automated  documentation— programs  as  docu- 
mentation, programs  generating  documentation,  documentation  generating  programs,  and 
executable  documentation  as  part  of  a  program.    In  conjunction  with  all  of  these  approaches 
those  documents  that  are  not  an  integral  part  of  the  program  can  be  produced  using  text 
editors  and  word  processors.    Herb  Hecht  summed  up  by  stating  that  surveys  have  shown  that 
documentation  tools  are  well -liked  by  programmers. 


However,  two  reservations  were  expressed  with  regard  to  this  promising  approach  to 
documentation.    Herb  Hecht  commented  that  fully  automated  documentation  is  not  yet  feasible 
Human  intervention  is  still  needed  to  disclose  general  intent  and  patterns  in  the  programs. 
In  addition,  all  of  the  participants  admitted  that  their  systems  had  limitations.    All  of 
these  systems  are  either  prototypes,  are  available  only  on  specific  machines,  or  are  suit- 
able only  to  specific  types  of  systems  or  applications.    Frequently,  tools  are  incompatible 
with  other  tools  available  on  the  same  system. 


A  concern  expressed  by  several  members  of  the  audience  was  whether  tool  usage  to  aid  o 
replace  the  programmer  would  further  increase  the  distance  between  software  developers  and 
users.    Several  of  the  panelists  responded  that  the  major  part  of  a  programmer's  time  is 
currently  spent  on  "housekeeping  tasks."    The  tools  can  take  over  these  tasks— by  removing 
them  from  the  programmer's  domain  (Blum),  hiding  them  from  the  user  (Ting),  or  eliminating 
the  distinction  between  specifications  and  programs  (Malhotra).    This  allows  the  programmer 
to  concentrate  on  the  functional  part  of  the  program,  and  on  identifying  and  satisfying  the 
users'  needs. 


An  additional  theme  was  repeated  a  number  of  times.    In  order  to  capitalize  on  any  of 
these  advances  in  documentation  development,  management  must  become  committed  to  the 
necessity  of  documentation  as  an  inseparable  part  of  the  software  development  process. 


This  session  demonstrated  that,  through  the  use  of  automated  tools,  documentation 
development  can  be  a  dynamic  process,  reaping  all  the  benefits  of  the  new  advances  in 
technology. 
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Introduction 


ADP  systems  are  recognized  as  evolving  from  initial  concept  to  final  operation.  This 
evolution  is  called  the  life  cycle  and  is  characterized  by  several  major  events  or  mile- 
stones which  delineate  the  life  cycle  phases  of  the  system.    These  milestones  provide  the 
means  of  measuring,  evaluating,  and  thereby  controlling  the  progress  of  the  development 
effort.    It  is  recognized  that  there  are  many  different  terminologies  to  identify  the 
phases  and  the  associated  documentation. 

In  February  1976,  the  National  Bureau  of  Standards  issued  the  Federal  Information  Proces- 
sing Standards  Publication  (FIPS  PUB  38):    "Guidelines  for  Documentation  of  Computer 
Programs  and  Automated  Data  Systems"  (February  15,  1976).    This  document  presents  detailed 
content  guidelines  for  ten  document  types  generally  prepared  during  the  Development  Phase. 

This  was  followed  in  1979  with  FIPS  PUB  64  "Guidelines  for  Documentation  of  Computer 
Programs  and  Automated  Data  System  for  the  Initiation  Phase  (August  1,  1979). 

Taken  together,  these  two  FIPS  PUBS  are  the  first  attempt  at  a  government-wide  Documenta- 
tion Standard  and  today  are  widely  used  within  the  Federal  ADP  Community. 

a .  Initiation  Phase 

During  the  Initiation  Phase,  the  objective  and  general  definitions  of  the 
requirements  are  established.    Feasibility  studies,  cost  benefit  analyses  and 
other  documents,  determined  by  agency  procedures  and  practices,  are  developed. 

b.  Development  Phase 

The  Development  Phase  is  broken  down  into  four  stages;  Definition,  Design,  Pro- 
gramming, and  Test. 

The  DEFINITION  stage  defines  the  functional  and  performance  requirements  needed  to 
initiate  the  design  as  well  as  to  confirm  that  the  completed  software  will  meet 
the  objectives.    These  functional  Requirements  define  what  the  software  must  do 
rather  than  how  it  is  to  be  done. 

During  the  DESIGN  stage,  the  System  and  Program  Specifications  are  developed. 
These  are  detailed  specifications  of  the  internal  construction  of  the  software, 
for  use  by  programmers  who  will  implement  the  design. 

During  the  PROGRAMMING  stage,  program  language  statements  or  "code"  is  produced 
that  meets  the  Design  Specifications.  Program  or  Unit  Testing  also  takes  place 
during  this  stage. 

During  the  TEST  stage.  System,  Integration  and  Acceptance  Testing  takes  place 
according  to  a  Test  Plan  prepared  in  a  previous  stage. 

c.  Operation  Phase 

During  the  Operation  phase,  software  is  maintained  and  enhanced  as  additional 
requirements  are  identified. 
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Sufficient  experience  in  the  use  of  these  documentation  standards  now  exists,  and 
it  is  appropriate  to  stop  and  evaluate  the  present  standards.    Therefore,  the 
title  of  this  session  "Do  Existing  Standards  Work"?    The  focus  is  on  how  these 
standards  can  be  modified  to  be  responsive  to  new  initiatives  as  well  as  new 
methods  and  procedures  for  preparing  the  required  documents. 

Ronald  Thies  in  his  paper  "Documenting  System  Security"  addresses  the  new  emphasis 
on  System  Security  as  a  result  of  0MB  Circular  A-71  TM  No.  1,  "Security  of  Federal 
Automated  Information  Systems."    The  paper  presents  an  approach  to  documenting 
system  security  which  provides  for  the  threading  of  security  throughout  the 
documentation  life  cycle.    The  approach  requires  that  security  requirements  are 
thoroughly  described  in  the  Functional  Requirements  Document  and  that  security  is 
specifically  addressed  as  it  applies  to  each  of  the  subsequent  documents. 

It  is  interesting  to  note  that  these  changes  have  successfully  been  accomplished 
within  the  FIPS  PUB  38  framework. 

Traditionally,  documentation  is  prepared  by  the  developers.    Personnel  working  on 
System  Requirements  prepare  the  Requirements  documentation.  System  Designers 
prepare  the  Design  Documentation,  etc.    Patrick  0' Conor  and  Samuel  Redwine 
described  an  environment  where  for  unique  reasons  this  method  didn't  work.  In 
their  experience  in  establishing  a  technical  writing  organization  for  the  purpose 
of  preparing  ADP  software  documentation. 

The  final  paper  in  this  session  by  Robert  Hegland  is  entitled  "An  Overview  of  the 
Department  of  Defense  Automated  Data  Systems  Documentation  Standard  -  an  adaptable 
standard."    It  briefly  describes  the  DOD  standard,  which  is  very  similar  to  FIPS 
PUB  38  and  in  fact  was  used  as  a  point  of  departure  by  the  intergovernmental  team 
that  developed  the  NBS  Standards. 
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Documenting  Systems  Security 

Ronald  G.  Thies 

Systems  Specialist,  Standards  and 

Quality  Control  Staff 
Office  of  ADP  Systems  Development 
U.S.  Department  of  Housing  and  Urban  Development  (HUD) 

This  paper  presents  an  approach  to  documenting 
system  security  which  provides  for  the  threading 
of  security  throughout  the  documentation  life 
cycle.    The  approach  requires  that  security 
requirements  are  thoroughly  described  in  the 
Functional  Requirements  Document  and  that  security 
is  specifically  addressed  as  it  applies  to  each 
subsequent  document.    Its  structure  provides  for 
the  convenience  of  security  reviews  necessary  to 
attain  system  certification.    To  describe  the 
approach,  revised  security  sections  were  prepared 
for  the  Functional  Requirements  Document, 
System/Subsystem  Specification,  Test  Plan,  and 
Test  Analysis  Report  which  are  described  in  the 
current  FIPS  PUB  38  (1). 


1.  INTRODUCTION 

1.1  Background 

With  the  issuance  of  0MB  Circular  A-71,  Transmittal 
Memorandum  No.  1,  Security  of  Federal  Automated  Information  Systems, 
on  July  27,  1978,  and  subsequent  guidance  from  NBS,  0PM,  and  GSA 
(3)  (4)  (5)  (6),  documentating  system  security  is  being  viewed 
with  a  new  perspective  in  Federal  Government.    Operating  agencies 
must  now  consider  documenting  system  security  an  integral  part 
of  the  development  process  not  only  for  the  very  sensitive  but  for 
all  systems.    The  old  assumption  that  "a  system  is  non-sensitive 
unless  specifically  designated  sensitive"  must  now  be  replaced 
with  the  assumption  that  "a  system  is  sensitive  unless  specifically 
designated  non-sensitive."    In  other  words  system  security  must  be 
addressed  and  documented  at  the  outset  of  the  development  process 
to  determine:    (a)  the  degree  of  sensitivity  to  place  on  the  system 
and  (b)  the  amount  of  effort  to  devote  to  the  development  and 
documentation  of  appropriate  security  safeguards. 
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The  documents  in  the  current  version  of  FIPS  PUB  38  (1) 
address  security  in  somewhat  general  terms.    Agencies  using  this 
publication  as  their  primary  documentation  standards  will  have 
to  augment  its  coverage  of  security  to  assure  that  specific  security 
requirements  are  adequately  described  in  the  Functional  and  Data 
Requirements  Documents  and  that  appropriate  safeguards  are  described 
and  evaluated  in  the  subsequent  documents.    It  is  important  that 
improved  coverage  of  system  security  be  included  in  the  forthcoming 
revision  to  FIPS  PUB  38  (1).    This  improved  coverage  should  be 
structured  so  that  it  provides  for  the  security  reviews  necessary 
to  attain  system  certification,  a  specific  requirement  of  0MB  Circular 
A-71,  Transmittal  Memorandum  No.  1  (2). 

1.2  Purpose 

The  purpose  of  this  paper  is  to  present  an  approach  to 
threading  security  throughout  the  documentation  life  cycle.    It  is 
hoped  that  this  approach  or  a  similar  approach  will  be  considered 
in  the  next  revision  of  FIPS  PUB  38  (1). 

1.3  Scope 

This  paper  contains  proposed  security  sections  for  the  Functional 
Requirements  Document,  System/Subsystems  Specification,  Test  Plan,  and 
Test  Analysis  Report  which  are  described  in  FIPS  PUB  38  (1).  Preceding 
each  proposed  security  section  is  a  brief  narrative  explaining  the 
rationale  behind  its  content.    Determining  the  sensitivity  of  a  system, 
and  conducting  and  documenting  a  risk  analysis  (5)  of  a  system  are 
pre-requisites  to  the  preparation  of  the  FIPS  PUB  38  (1)  documents 
and  are  not  covered  in  this  paper. 

1.4  Limitations 

Documentation  of  system  security  in  most  cases  cannot  be  isolated 
in  a  single  section  of  a  document.  It  is  not  intended  that  all  security 
details  be  documented  under  the  separate  security  sections  presented 
in  this  paper.    These  security  sections  serve  to  remind  the  authors  of 
the  importance  of  security  and  provides  for  the  summarizations  of  all 
security  considerations  as  applied  to  a  particular  document  type. 

Length  limitations  for  the  papers  precluded  the  author  from 
presenting  proposed  security  sections  for  all  ten  documents  described 
in  FIPS  PUB  38  (1).    Four  documents,  which  best  demonstrate  the 
threading  effect  of  security,  were  selected  for  presentation  in  this 
paper. 
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2.    PROPOSED  SECURITY  SECTIONS 


2.1    Functional  Requirements  Document  (FRD) 

As  pointed  out  in  FIPS  PUB  73  (6),  Section  6.1,  security 
requirements  must  be  adequately  defined  before  software  development 
can  proceed.    Therefore,  heavy  emphasis  has  been  placed  on  the 
security  requirements  in  the  FRD,  making  that  document  the 
cornerstone  for  building  security  safeguards  into  the  resulting 
system.    A  proposed  security  section  for  the  FRD  is  shown  in  Figure  1. 
It  is  intended  that  the  current  Section  5  of  the  FRD,  Development 
Plan,  be  changed  to  Section  6. 


5.  SECURITY. 

5.1  BACKGROUND  INFORMATION.    Provide  background  information 
which  reflects  on  the  sensitivity  of  the  application. 
Include  justification  for  the  degree  of  sensitivity 
placed  on  the  system  such  as,  conformance  to  the 
Privacy  Act  of  1974,  protection  of  critical  decision 
making  information,  preservation  of  fair  competition 

in  the  private  sector,  protection  of  saleable 
information,  etc. 

5.2  CONTROL  POINTS,  VULNERABILITIES,  AND  SAFEGUARDS. 
Provide  a  description  of  each  control  point,  the 
vulnerabilities  at  the  control  point,  and  the 
safeguard  requirements  to  reduce  the  risk  at  the 
point  to  an  acceptable  level. 

5.2.1     Control  Points.    Describe  the  points  in 
the  system  where  there  is  a  defined 
vulnerability  which  requires  specific 
safeguards.    A  control  point  can  be  located 
at  any  interface  where  data  move  between 
two  administrative,  physical,  or  technical 
entities.    Control  points  should  be 
considered  in  three  broad  categories:  input, 
process,  and  output. 

a.    Input  Control  Points 

(1)  Source  Origin.    Identify  where 
input  data  will  be  collected, 
prepared,  and  entered  to  the 
system. 

Figure  1.    Proposed  Security  Section  for  the  FRD 


133 


Figure  1.  Cont'd  

(2)  Source  Backup.  Identify  where 
source  data  will  be  collected, 
stored,  and/or  destroyed  after 
input  to  the  system. 

(3)  Data  Entry.    Identify  the  personnel 
positions  and  the  terminals 

that  will  be  permitted  to  perform 
data  entry,  update,  and  corrective 
actions. 

(4)  Error  Correction.  Identify 
the  points  where  data  input 
errors  will  be  detected,  reported, 
and  corrected. 

b.  Process  Control  Points. 

(1)  Accuracy  and  Completeness. 
Identify  the  points  in  the 
processing  cycle  where  the 
system  should  notify  the  user 
that  input  data  has  been  accepted 
and/or  that  the  requested  processing 
has  been  completed. 

(2)  System  (Programmed)  Interfaces. 
Identify  the  points  in  the 
processing  cycle  where  data 
are  to  be  internally  passed 

or  retrieved  to  or  from  other 
systems. 

c.  Output  Control  Points. 

(1)  Production.    Identify  personnel 
positions  and  terminals  that 
are  permitted  to  receive  output. 

(2)  Distribution.    Identify  the 
steps  and  personnel  positions 
involved  in  the  distribution 
and  disposition  of  computer 
output  products. 
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Figure  1,  Cont'd  

5.2.1.1    Vulnerabilities.    Describe  the  vulnerabilities 
at  each  control  point  identified  in  5.2.1.  A 
vulnerability  is  a  design,  implementation,  or 
operational  condition  inherent  in  the 
application  or  system  which  lends  itself  to 
error  and/or  loss  or  compromise  of  information. 


5.2.1.2    Safeguards.    Describe  the  safeguard 

requirements  at  each  control  point  to 
reduce  the  vulnerabilities  to  acceptable 
levels.    Consider  at  least  the  following 
areas: 


a.       Administrative  Safeguards.  An 

administrative  safeguard  is  defined 
as  any  procedure  that  requires 
management  oversight;  i.e.,  requires 
supervision  to  assure  compliance. 

(1)  Personnel.    Identify  which 
personnel  positions  will  require 
security  clearances  because 

of  their  association  with  the 
proposed  system. 

(2)  Distribution.    Describe  any 
requirement  for  a  variance  from 
standard  distribution  procedures. 


(3)  Constrained  User  Environment.  Describe 
any  requirement  to  limit  operation 

of  the  proposed  system  to  certain 
terminals  or  periods  of  the 
day. 

(4)  Collection  and  Preparation.  Describe 
requirements  for  the  proper  control 
of  collection,  preparation,  and 
backup  of  input  data. 

(5)  Access/Permission.  Describe 
procedural  and  safeguard  of  lists 
of  personnel  authorized  to  access 
and  approve  change  requests  for  the 
system. 
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Figure  1.  cont'd  

b.  Physical  Safeguards.    Physical  safeguards 
are  defined  as  any  physical  means  that 
limit  access  to  data;  i.e.,  locked  rooms, 
vaults,  card/key  access,  and  locked  doors. 

(1)  Dedicated  Equipment.    Describe  any 
requirement  for  dedicated  equipment 

to  aid  in  maintaining  system  security. 
This  may  include  storage  media  as 
well  as  processors  or  terminals. 

(2)  Storage  and  Protection.  Describe 
requirements  for  onsite  and  offsite 
storage  and  protection  of  materials 
(programs,  data,  documentation,  etc.). 

c.  Technical  Safeguards.    Technical  safeguards 
are  defined  as  any  automated  process  that 
assures  appropriate  processing;  i.e., 
passwords,  audit  trail  reports,  etc. 

(1)  User.    Describe  any  requirement 
for  managing  user  access. 

(2)  Process  Safeguards.    Describe  the 
need  for  any  unique  data  validation 
procedures  which  may  provide  added 
integrity. 

(3)  Describe  any  unique  automated  output 
report  labeling  requirements  to  be 
imposed  on  the  system. 


5.3    SYSTEM  MONITORING  AND  AUDITING.    Describe  user 
requirements  for  the  production  of  an  audit 
trail  including  automated  reports  or  journals 
necessary  to  monitor  the  system. 

5.3.1  Journalizing  (Event  Recording).    Describe  the 
journalizing  requirements  for  the  system. 
Journalizing  is  the  recording  of  selected  events 
as  they  occur  within  the  system  and  provides  the 
basis  for  monitoring  the  processing  and 
use  of  data  and  the  use  of  computer  resources. 
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Figure  1.  Cont'd  

a.  Triggering  Criteria.  Describe 
the  conditions  (functions,  events, 
dates,  times,  unusual  circumstances, 
etc.)  which  will  trigger  the  creation 
of  an  entry  on  the  automated  journal. 

b.  Identification  Information.  Describe 
the  identification  information, 
external  to  the  application  system, 
such  as  date,  time,  system  or  function 
ID,  user  name,  terminal  ID  and  location 
etc.,  to  be  recorded  in  the  journal 
entry. 

c.  Application  data.    Identify  the 
application  systems  data  to  be 
recorded  for  each  type  of  journal 
entry. 

d.  Investigation.    Describe  the  procedural 
and  management  requirements  for 
review  and  follow-up  of  the  journal. 

5.3.2    Audit  Trail.    Describe  any  additional  user 
requirements  for  an  audit  trail.  These 
requirements  include  such  values  as  total 
transactions  processed  by  location  and  time; 
total  records  added,  updated,  and  deleted  by 
location  and  time;  and  various  dollar  totals. 
As  an  example,  financial  accounting  systems 
must  comply  with  GAO  requirements  for  an 
audit  trail  from  source  documents  through  the 
system  to  outputs. 
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2.2    System/Subsystem  Specification 

The  threading  effect  of  security  in  the  System/Subsystem 
Specification  is  accomplished  through  backward  reference  to  the  FRD. 
A  proposed  security  section  is  shown  in  Figure  2.    Note  that  in 
paragraph  5.2  of  Figure  2,  all  security  requirements  defined  in  the 
FRD  must  be  addressed.    It  is  intended  that  Subsection  3.4  be  deleted 
from  the  current  document  and  be  replaced  by  a  separate  Section  5 
covering  security.    The  current  Section  5,  Program  Specifications, 
would  then  become  Section  6. 


5.  SECURITY 

5.1  SECURITY  REQUIREMENTS.    Summarize  the  overall 
security  and  privacy  requirements  imposed  on 
the  system/subsystem. 

Include: 

a.  Privacy  Act  Compliance. 

b.  Data  Security. 

c.  Data  Integrity. 

d.  Access/Update  Authority  Controls. 

e.  Privacy  Act  Disclosure  Accounting. 

If  no  specific  security  requirements  are  imposed 
on  the  system,  state  this  fact. 

5.2  SECURITY  SAFEGUARDS.    Describe  or  summarize 
the  security  safeguards  included  in  the  systems 
design  and  how  they  satisfy  the  security  requirements. 
If  a  safeguard  has  been  described  as  an  integral 

part  of  the  system  logic  in  other  sections 
of  this  document,  reference  should  be  made 
to  the  appropriate  sections.    When  appropriate, 
identify  the  individual  programs  in  the  system 
which  are  involved  in  satisfying  a  particular 
safeguard  requirement.    All  safeguard  requirements 
described  in  Section  5.2.1.2  of  the  FRD  should 
be  addressed  in  this  section  as  follows: 

a.       Administrative  Safeguards.    An  administrative 
safeguard  is  a  procedure  that  requires 
management  oversight  to  assure  compliance. 
Describe  the  administrative  safeguards 
which  have  been  included  in  the  systems 
design.    If  an  administrative  safeguard 
falls  outside  the  systems  design,  describe 
any  assumptions  made  about  the  safeguard 
and  how  the  designed  system  will  interface 
with  the  safeguard. 


Figure  2.    Proposed  Security  Section  for  the  System/Subsystem 
Specification 
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Figure  2.  Con't.  

b.  Physical  Safeguards.    Physical  safeguards 
are  defined  as  any  physical  means  that  limit 
access  to  the  data;  i.e.,  locked  rooms,  vaults, 
and  card/key  access.    Describe  the  physical 
safeguards  which  have  been  designed  into 

or  are  required  by  the  system.    If  a  required 
physical  safeguard  already  exists  or  the 
responsibility  for  its  implementation  falls 
outside  the  application  system  development, 
describe  any  assumptions  made  about  the 
safeguard  and  how  the  system  will  use  the 
safeguard. 

c.  Technical  Safeguards.    Technical  safeguards 
are  defined  as  any  automated  process  that 
assures  appropriate  processing,  controls 
access  to  the  data,  or  provides  audit  trail 
information.    Describe  where  and  how  technical 
safeguards  are  to  be  implemented  in  the  system. 
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2.3    Test  Plan 


It  is  important  that  testing  of  all  security  capabilities 
be  included  in  the  test  plan.    The  proposed  security 
section,  shown  in  Figure  3,  requires  that  all  security 
requirements  and  capabilities  described  in  previous 
system  documents  be  addressed,  even  if  they  are  excluded 
from  testing. 


5.  SECURITY 

5.1    SECURITY  SAFEGUARD  TEST  DESCRIPTIONS. 

Summarize  the  security  safeguard  requirements 
imposed  on  the  system  and  specifically  identify 
the  test(s)  described  under  Section  4  of  this 
document  which  will  demonstrate  the  ability  of 
the  system  to  satisfy  each  security  safeguard 
requirement.    Identify  required  safeguards 
which  cannot  be  tested  within  the  scope  of 
this  test  plan.    Provide  an  explanation 
concerning  the  responsibilities  for  testing 
these  safeguards  or  why  testing  is  not 
necessary.    All  security  safeguard  requirements 
described  in  Section  5.2.1.2of  the  FRD  and/or 
Section  5.2  of  the  System/Subsystem  Specifications 
should  be  addressed  in  this  section.    If  security 
requirements,  functions,  and  tests  have  been 
listed  under  Sections  3.1.1,  3.1.2,  and  3.1.3 
of  this  document,  reference  should  be  made 
to  those  sections. 


Figure  3.    Proposed  Security  Section  for  the  Test  Plan 
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2.4    Test  Analysis  Report 


To  support  system  certification,  a  requirement  of  0MB  Circular 
A-71,  Transmittal  Memorandum  No.  1  (2),  it  is  necessary  in  the 
Test  Analysis  Report  to  break  out  security  in  a  separate  section. 
This  will  allow  for  easy  review  of  the  report  to  determine  if 
the  system  meets  previously  established  security  requirements. 
A  proposed  security  section  is  shown  in  Figure  4. 


5.  SECURITY 

5.1  SECURITY  TEST  SUMMARY.    Summarize  the  security 
capabilities  which  were  included  in  the  systems 
test  and  itemize  the  specific  security  deficiencies 
detected  during  the  conduct  of  the  test.  The 
results  of  the  individual  tests,  system  findings, 
and  a  thorough  analysis  of  deficiencies  along  with 
recommendations  have  been  covered  in  Sections  2, 

3,  and  4  of  this  document.    The  portions  of  these 
sections  which  specifically  address  systems 
security  should  be  referenced  in  this  section. 
If  no  deficiencies  were  detected  during  the 
systems  test,  state  this  fact. 

5.2  SECURITY  TEST  ANALYSIS.    Based  on  the  results 
of  the  systems  test,  provide  a  statement 
concerning  the  adequacy  of  the  system  to  meet 
overall  security  requirements  as  described 

in  Section  5  of  the  FRD  and  Section  5  of  the 
System  Test  Plan. 


Figure  4.  Proposed  Security  Section  for  The  Test  Analysis  Report 
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USING  FIPS  PUB  38:  A  PRACTICAL  EXPERIENCE 
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Science  Management  Corp. 


ABSTRACT: 

The  paper  describes  the  exper- 
ience of  the  authors  as  they  estab- 
lished a  technical  writing  organi- 
zation for  the  purpose  of  preparing 
computer  software  documentation 
with  the  FIPS  PUB  38  Guideline. 
The  evolution  of  the  documentation 
group  within  the  corporate  context 
is  presented  along  with  the  methods 
that  were  developed  for  the  prod- 
uction of  documentation.  The  per- 
vasive way  in  which  the  Guideline 
influenced  the  operation  and  con- 
formation of  the  group's  procedures 
is  discussed.  Problems  the  authors 
encountered  with  the  use  of  a  stan- 
dard derived  directly  from  FIPS  PUB 
38  and  the  solutions  evolved  to 
counter  them  are  shown. 

Keywords:  Documentation;  Structured 
Interview;  Technical  Writing;  Doc- 
umentation Guidelines;  Documenta- 
tion Procedures;  Case  Study;  Doc- 
umentation Organizations. 


PREFACE: 

The  authors  organized  a  technical 
writing  group  for  the  purpose  of  preparing 
computer  systems  documentation  within  a 
medium  sized  company  whose  principle  product 
is  computer  systems  software  and  services. 
Much  of  the  software  built  by  the  company 
was  subject  to  requirements  to  be  documented 
according  to  the  U.S.  Dept.  of  Energy  78-6 
Documentation  Standard,  a  derivative  (almost 
verbatim)  of  the  FIPS  PUB  38  Guideline.  We 
will  describe  the  development  difficulties 
encountered,  and  the  detailed  documentation 
methodology  as  it  evolved.  The  paper  will 
show  the  pervasive  way  in  which  the  standard 
influenced  the  formation,  and  operating  pro- 
cedures of  this  technical  writing  group. 

The  group  was  judged  to  be  highly  suc- 
cessful as  was  evidenced  by  verbal  and  writ- 
ten expressions  of  satisfaction  from  its 
clients,    and   by   issuance   of   praise  from 


Samuel  T.  Redwine,  Jr. 
MITRE  Corp. 

higher  management.  Problems  of  quantity  and 
quality  in  using  FIPS  PUB  38  for  the  pro- 
duction of  computer  systems  documentation 
had  to  be  solved,  and  due  to  techniques  des- 
cribed in  this  paper,  this  group  was  able 
not  only  to  produce  technical  documentation 
at  substantially  reduced  costs,  but  also  to 
free  scarce  systems  staff  personnel  for 
roles  in  which  they  were  better  suited  and 
util  ized. 


1.  THE  STARTING  POINT: 

In  the  late  summer  of  1979  one  of  the 
authors  (S.T.R.)  became  the  new  manager  of  a 
forty  person  systems  staff  providing  con- 
tract systems  and  programming  support  to  the 
Energy  Information  Administration  (EIA)  for 
a  variety  of  users  in  the  Dept.  of  Energy 
(DOE). 

He  found  the  following  situation:  the 
systems  staff  had  grown  from  less  than  ten 
to  forty  persons  performing  a  dozen  concurr- 
ent, independent  projects  under  four  project 
managers.  The  contract,  a  task  order  type, 
called  for  separate  budgeting  and  scheduling 
for  each  task  order.  Documentation  for  the 
systems  produced  under  each  task  was  requir- 
ed to  conform  to  EIA  documentation  stand- 
ards. The  EIA  Standard  (referred  to  by  its 
issuance  number  78-6)  is  a  typographically 
poor  copy  of  the  FIPS  PUB  38  Guideline. 

Much  work  had  been  done  on  a  code 
first,  document  later  basis.  This  had  fre- 
quently resulted  in  documentation  being 
omitted  altogether.  When  the  author  first 
began  to  manage  the  group,  no  examples  of 
good  documentation  prepared  by  the  systems 
staff  and  using  the  guideline  could  be  found 
despite  a  sincere  search  effort.  This 
search  had  included  the  client  organization 
that  had  mandated  the  use  of  the  standard. 
Despite  this,  documentation  was  found  to  be 
of  great  importance  to  DOE  client  opinion 
since  it  was  the  most  visible  evidence  of 
the  existence  of  their  systems.  Lack  of 
documentation,  and  bad  documentation,  had 
been  a  frequent  cause  of  complaint  against 
DOE  technical  managers  by  the  DOE  clients 
for  whom  the  applications  were  developed. 
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It  therefore  formed  a  major  (perhaps  the 
single  largest)  determinant  of  client 
perception  of  corporate  and  systems  building 
competance. 

Identification  of  the  need  for  the 
technical  writing  group  arose  from  the  in- 
ability of  our  systems  staff  personnel  to 
prepare  documentation  according  to  the  DDE 
Standard.  This  inability  to  cope  with  the 
Standard  came  from  two  sources;  the  lack  of 
writing  ability  among  the  systems  people, 
and  the  lack  of  understanding  they  had  in 
trying  to  interpret  the  Standard.  The  typ- 
ical response  of  the  systems  people  when 
confronted  by  the  need  to  prepare  manual s 
using  the  Standard  was  to  complain  of  its 
paradoxical  imposition  of  requiring  specific 
rubrics  to  be  used  which  were  themselves 
subject  to  interpretation.  Parkinson's  Law 
was  much  in  evidence  in  this,  and  systems 
staff  were  loath  to  expend  creative  energy 
in  the  direction  of  documentation,  indicat- 
ing most  often  that  theirs  was  a  higher 
mission  in  life,  i.e.  programming  and  sys- 
tems analysis. 

Using  the  78-6  Standard  often  required 
determining  what  the  Standard  meant.  Even 
knowledgeable  systems  people  who  were  well 
acquainted  with  the  vocabulary  used  in  78-6 
were  at  a  loss  to  understand  its  intentions. 
Most  of  the  systems  staff  could  not  write 
readable  English  in  any  event,  and  most  pro- 
ject managers  spent  extraordinary  amounts  of 
overtime  editing  and  rewriting.  But,  the 
project  managers  themselves  were  not  pro- 
fessional writers  or  editors.  The  documen- 
tation efforts  thus  produced  were  not  only 
very  poor,  but  were  being  written  with  the 
company's  most  expensive  resources.  Their 
documentation  efforts  impacted  their  systems 
development  activities  and  were  contributing 
to  major  delays. 

2.  EARLY  HISTORY: 

The  beginning  of  the  technical  writing 
group  occured  when  it  was  recognized  that 
the  efforts  of  the  systems  people  were 
fruitless  in  this  activity.  A  technical 
writer  was  recruited  largely  to  off-load  the 
burdens  of  our  project  managers.  The  person 
hired,  while  familiar  with  data  processing 
and  a  sound  writer,  had  no  experience  writ- 
ing D.P.  documentation  or  with  the  DOE  78-6 
Standard.  This  single  technical  writer 
could  not  begin  to  meet  the  large  demand  for 
documentation  manuals.  Training,  role  guid- 
ance, and  an  organized  relationship  with  the 
systems  personnel  were  not  provided.  This, 
and  the  unrealistic  demands  of  our  project 
managers    created    difficulties    for  the 


writer.  All  of  the  project  managers  demand- 
ed technical  writing  time  on  arbitrary 
schedules  which  were  typically  an  order  of 
magnitude  too  short  a  time  frame  to  allow 
production.  They  dismissed  in  an  offhand 
manner  any  suggestion  that  this  caused  diff- 
iculties or  that  documentation  was  a  rigo- 
rous aspect  of  the  computerized  environment 
demanding  respect  in  its  own  right. 


A  few  weeks  after  the  hiring  of  the 
technical  writer,  a  Quality  Assurance  (OA) 
Manager  (author  P.O'C.)  was  brought  on  staff 
to  address  software  quality  issues,  estab- 
lish QA  in  the  systems  staff  environment, 
and  to  bring  better  order  to  the  process  of 
systems  construction.  Initial  OA  efforts 
were  aimed  at  the  creation  and  installation 
of  programming  standards,  and  the  procedures 
involved  in  processing  systems  task  orders 
from  DOE  clients.  This  led  to  QA  review  of 
systems  staff  products  including  documenta- 
tion. These  reviews  pointed  to  the  need  for 
reform  of  the  management  approach  to  docu- 
mentation production  and  also  to  reform  of 
the  quality  of  the  documentation  which  was 
still  larqely  being  produced  by  the  systems 
staff. 

A  second  technical  writer  was  recruit- 
ed. It  was  clear  however,  that  more  sweep- 
ing changes  were  required  in  the  production 
of  documentation.  This  was  punctuated  by  a 
particular  task:  the  "Lloyds  Shipping  Index 
System"  (LSIS)  which  entered  the  local 
corporate  mythology  as  the  "Lloyds  Crunch". 
(The  Lloyds  of  London  Insurance  organization 
supplied  certain  information  for  DOE  data 
bases  on  oil  tanker  traffic.)  The  project 
had  slipped  several  due  dates,  generated 
copious  amounts  of  overtime,  and  had  created 
gross  image  problems  for  us  with  respect  to 
our  client. 

The  LSIS  system  had  been  finalized  and 
the  documentation  for  it,  which  had  been 
produced  by  the  systems  staff,  was  presented 
for  quality  assurance  review  less  than  three 
days  before  the  scheduled  delivery  date. 
The  documentation  proved  to  be  disastrously 
poor;  and  was  made  all  the  more  pitiable 
given  the  agonized  overtime  labor  of  the 
systems  personnel  that  had  been  used  to  pro- 
duce it.  Most  rubrics  were  marked  "not 
applicable",  while  others  had  incoherent 
single  sentence  explanations  that  seemed  to 
bear  little  reference  to  the  definition  for 
the  rubric  in  the  DOE  Standard. 
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An  embarrassing  renegotiation  with  the 
client  on  the  due  date  and  a  massive  effort 
on  the  part  of  the  QA  manager  and  technical 
writer  were  required  to  prepare  a  completely 
new  set  of  manuals.  The  result  was  an  acc- 
eptable deliverable  that  solved  the  critical 
situation  created  by  the  Lloyds  task,  and 
provided  the  first  fledgling  example  of  what 
our  78-6  Standard  documentation  should  look 
like. 

During  the  strenuous  effort  involved 
in  producing  the  Lloyds  documentation  on  an 
extremely  tight,  last  chance  schedule,  re- 
solve developed  among  the  participants  and 
management  not  to  repeat  the  mistakes  of  the 
past.  The  QA  manager  prepared  a  long  memo 
proposing  a  new  approach  to  the  preparation 
of  documentation  employing  a  separate  tech- 
nical writing  group  organized  on  a  par  with 
the  systems  staff.  The  memorandum  presented 
cost,  organizational,  and  quality  arguments. 
The  response  of  our  higher  management  was 
skeptical  approval,  and  we  began  to  recruit 
writing  staff  and  move  toward  a  better 
documentation  production  approach. 

Documentation  improvement  efforts  re- 
quired not  only  internal  changes,  but  also 
client  education.  The  client  personnel  in- 
volved in  the  different  development  tasks 
had  varied  backgrounds  ?nd  many  had  never 
seen  good  Standard  documentation  in  their 
federal  environments.  Most  wanted  less 
documentation  than  was  required  by  the  con- 
tractual necessity  to  conform  to  the  DOE 
Standard.  They  did  not  want  to  pay  for  it 
and  had  a  philosophy  that  every  dollar  not 
spent  on  programming  was  wasted.  Substant- 
ial pursuasion  efforts  were  required. 


3.  DOCUMENTATION  PRODUCTION: 

There  are  several  key  concepts  in  our 
production  methodology.  We  do  not  employ 
technically  trained  writers  (i.e.  prog- 
rammers) to  prepare  technical  documentation. 
We  have  developed  and  tested  in  practice  a 
set  of  simplistic,  almost  mechanical,  tech- 
niques to  aid  in  the  production  of  stand- 
ardized manuals;  and  have  provided  these 
"tricks"  to  people  with  demonstrated  writing 
ability.  The  "tricks"  and  the  people  have 
in  turn  been  embedded  in  a  distinct,  con- 
trollable, documentation  production  pro- 
cedure. Overall  the  results  were  striking. 
We  achieved  an  order  of  magnitude  increase 
in  the  productivity  factor  for  documenta- 
tion. We  also  freed  many  systems  staff 
labor  hours,  and  this  directly  resulted  in  a 
marked  decrease  in  systems  due  date  slipp- 
ages, and  other  problems. 


The  fundamental  premise  underlying  our 
approach  is  specialization  of  labor.  It 
proposed, 

"let  systems  staff  build  systems, 
and  let  writers  write  documentation." 

The  common  sense  of  this  proposition  qiven 
our  experience  with  having  programmers  write 
documentation  was  inescapable:  it  was  a 
gross  mistake  to  force  the  systems  staff  to 
write  manuals  since  they  disliked  writina, 
did  not  comprehend  (or  wished  to  comprehend) 
the  78-6  Standard,  and  could  not  write 
English  in  any  event. 

3.1  The  Documentation  Organization: 

The  organization  was  composed  of  five 
technical  writers  reporting  to  a  senior 
technical  writer.  The  group  was  olaced 
under  the  QA  Manager  who  also  functioned  as 
the  Documentation  Manager.  This  organ- 
ization had  two  noteworthy  features.  One  is 
the  position  of  the  aroup  under  the  Quality 
assurance  function.  The  second  is  the  ex- 
istence of  a  senior  technical  writer  in 
addition  to  the  group  manager.  The  group's 
organization  under  quality  assurance  imposed 
a  great  concern  for  the  quality  of  the  doc- 
umentation products.  This  was  true  not  only 
of  the  mechanical  aspects  of  documentation 
quality,  but  was  extended  with  special  em- 
phasis to  the  writing:  the  English  itself. 
Finding  itself  with  the  necessity  of  prod- 
ucing written  products,  the  QA  function  was 
determined  that  no  one  would  ever  have  a 
legitimate  opportunity  to  complain  of  poor 
quality  documentation.  Rigorous  require- 
ments for  writing,  review  and  rewriting  were 
imposed.  The  group's  de  facto  motto  became, 
"rewrite  is  a  way  of  life." 

The  role  of  the  senior  technical 
writer  emerged  as  an  administrative  nec- 
essity. The  demands  of  scheduling,  review 
and  rewrite,  record  ^eeping,  olanninq  and 
estimating  required  that  one  of  the  writina 
staff  be  given  an  administrative  role  in 
addition  to  writing  duties  in  order  to  shift 
time  demands  from  the  QA/Documentation  Mana- 
ger. This  was  also  part  of  a  goal  in  train- 
ing to  ensure  that  an  additional  person  knew 
how  to  perform  the  production  scheduling  and 
other  adminstrative  functions  for  the  group 
in  the  absence  of  the  principal  manager. 
The  staff  of  the  technical  writing  group 
never  exceeded  seven  persons.  There  was 
little  need  for  further  suborgani zati on . 
However,  we  recognize  that  separating  docu- 
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mentation  management  from  QA  would  provide 
desirable  organizational  independence  during 
reviews. 

The  people  who  comprised  the  technical 
writing  group  had  diverse  backgrounds,  but 
several  obvious  common  characteristics. 
Their  professional  diversity  spanned  from 
public  administration  to  english  literature, 
their  personal  diversity  from  genealogical 
research  to  macrame' ,  but  their  commonali- 
ties were  few  and  easily  identified.  They 
were  al 1 ; 

0         intelligent  and  well 
educated, 

all  had  graduate  degrees,  or  had  attended 
graduate  school.  One  had  a  Phd.  They  could 
all; 

0         wri  te  wel  1  at  the 
outset, 

and  their  writing  improved  from  an  initially 
high  standard  with  limited  training  time,  on 
the  job  practice  and  writing  review.  With  a 
single  happenstance  exception; 

0         none  had  any  training  or 
experience  in  computer 
systems,  all  expressed 
skepticism  about  their 
ability  to  succeed  in 
the  role  of  technical 
wri  ter . 

0         All  were  aggressive,  and 
were  eager  to  try,  and 
to  learn. 

In  the  setting  that  developed  for  doc- 
umentation there  were  particular  require- 
ments that  arose  for  the  role  of  the  docu- 
mentation manager.  The  role  of  this  manager 
demanded  that  he  possess  writing  skills,  be 
able  to  recognize  good  writing  from  bad,  and 
be  able  to  identify  writing  talent  in 
others.    The  manager's  duties  included; 

0         Evolution  of  the 

procedures  (performing 
systems  analysis  on  the 
methods  of  producing 
documentation) , 

0         Writing  staff  training, 

0  Review,  and  rewrite, 

0         Writing  staff 
recruiting, 


0         Documentation  cost 
estimating, 

0  Production  scheduling, 

and 

0         Maintenance  of 

intracompany  rela- 
tionships related  to  the 
production  of  documents 
by  interfacing  with 
systems  staff. 

The  utilization  of  non- technical  per- 
sonnel to  write  computer  systems  materials 
requires  that  they  have  easy  and  immediate 
access  to  someone  who  can  explain  concepts 
and  provide  daily  guidance  on  technical 
matters.  It  is  a  key  point  of  productivity 
to  recognize  that  only  one  such  person  is 
required:  not  all  members  of  the  writing 
staff  must  be,  or  should  be,  systems  ex- 
perts. Simple  dollar/word  cost  efficiency 
precludes  such  an  approach.  It  is  not  an 
absolute  requirement  that  the  systems  expert 
in  the  writing  group  also  be  the  group's 
manager,  although  it  was  the  case  in  this 
instance,  and  worked  well. 

3.2  The  Documentation  Process: 

A  step  by  step  procedure  was  thouqht  ' 
out  for  the  process  of  preparing  docu- 
mentation according  to  the  7R-fi  Standard. 
The  utilization  of  non- technical  personnel 
for  writing  of  this  type  required  that  a 
standard  in  outline  form  be  employed.  Had 
it  not  been  that  a  standard  was  contract- 
ually required,  or  if  none  were  available, 
it  would  have  been  necessary  to  create 
standard  outlines  due  to  the  nature  of  the 
documentation  process  we  developed.  It 
would  not  have  been  possible  to  routinize  a 
production  procedure,  perform  meaningful 
cost  estimates,  or  gather  proper  statistics 
if  the  product  had  not  been  standardized. 

The  standard  to  be  used  may  be  arbi- 
trarily chosen,  but  meaningful  comparisons 
and  planning  are  only  possible  among  pro- 
ducts of  similar  conformation.  The  methods 
that  were  evolved  for  the  gathering  of  tech- 
nical information  for  the  preparation  of 
text  were  only  usable  if  guided  by  a  de- 
tailed outline  of  the  required  information. 
The  78-6  Standard  provided  such  an  outline. 
We  found,  in  our  prior  adverse  experience, 
that  writers  cannot  gather  material  or  cor- 
rectly organize  it,  without  the  guidance  of 
adequate  documentation  standards. 

Our  principal  method  of  gathering 
technical    material    for    preparation  of 
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manuals  is  the  "Structured  Interview".  The 
structured  interview  consists  of  tape  re- 
cording verbal  discussions  of  the  systems  to 
be  documented  during  interview  sessions 
guided  by  the  manual  outlines  provided  in 
the  Standard.  The  technical  writer  as 
interviewer  quizzes  a  systems  staff  inter- 
viewee by  reading  and  discussing  the  rubric 
definition  from  a  copy  of  the  standard  out- 
line in  a  conversational  manner.  The  inter- 
viewee is  asked  to  discuss  in  his  own  words 
the  information  called  for  in  each  rubric. 
The  interview  proceeds,  rubric  by  rubric 
until  the  basis  for  a  complete  manual  is 
recorded. 

Even  the  most  complicated  systems 
rarely  took  more  than  a  single,  forty  to 
sixty  minute  interview  per  manual.  This  was 
found  to  be  adequate  for  the  production  of 
most  manuals.  The  verbal  communications 
skills  of  the  technical  writers  and  systems 
staff  varied,  and  this  impacted  the  time  re- 
quired. Interviewing  was  not  a  mechanical 
process,  but  was  subject  to  the  nuance  of 
meaning  of  each  rubric  in  the  Standard. 
Moreover,  the  interpersonal  skill  of  the 
interviewer  influenced  the  quality  and 
quantity  of  the  information  obtained.  The 
involvement  of  systems  staff  consisted  of; 
participating  in  these  interviews,  providing 
miscellaneous  supplementary  materials  such 
as  flow  chart  sketches,  and  reviewing  draft 
manuals  for  the  accuracy  of  technical  con- 
tent. The  net  result  was  that  systems  staff 
spent  nearly  all  of  their  time  on  systems 
work. 


of  sequential  search  capability  by  physical 
sequence  of  taped  rubric  numbers  aides  the 
writer  in  finding  and  reviewing  interview 
material.  The  tape  cassettes  form  a  record 
that  is  reviewed  as  many  times  as  needed  by 
the  technical  writer.  The  technical  writers 
would  listen  to  these  structured  tapes,  ab- 
sorb and  digest  the  verbal  material,  and 
then  prepare  a  first  draft. 

Another  key  concept  in  the  process  of 
preparing  technical  manuals  was  the  realiza- 
tion that  there  are  different  types  of  Eng- 
lish. In  this  context  there  are  three 
types;  -spoken  English,  ordinary  prose 
English,  and  technical  prose  English.  The 
main  function  of  the  technical  writer  is  to 
be  a  converter  of  verbal  English,  as  found 
on  the  stream  of  consciousness  tape  record- 
ings, into  ordinary  prose,  and  then  via 
rewrite,  into  technical  prose. 

The  process  of  writing  a  standard  FIPS 
PUB  38  manual  was  broken  down,  into  a  seq- 
uence of  thirteen  discrete  steps.  Each  step 
consists  of  an  activity  having  duration  in 
time  which  is  marked  by  its  completion  date. 
Each  step  is  performed  by  a  single  individ- 
ual who  is  held  responsible  for  its  on- time 
completion.    The  steps  are; 

Activity  Responsible 
Person 

1.  Structured  Interview  Tech  Writer 

2.  First  Draft  Writing    Tech  Writer 


The  invention  of  the  structured  inter-  3. 
view  took  advantage  of  several  human  traits. 
It  was  found  that  even  the  most  introverted  4. 
staff  member  loved  to  talk  about  the  clever- 
ness he  had  built  into  his  COBOL,   or  TSO 
CLISTs.     In  the  process  of  verbalizing,  the  5. 
natural  order  of  ideas  concerning  the  system 
would  flow  out:  each  idea  queues  up  the  next 
in  its  natural  sequence.    The  tape  recorder  6. 
faithfully  captures  this  "stream  of  consci- 
ousness" and  the  outline  from  the  Standard  7. 
gives  it  directly  the  rough  form  of  a  verbal 
FIPS  PUB  38  manual  .  8. 

The  device  of  employing  a  tape  record-  9. 
er  also  frees  the  mind  of  the  interviewer 
from  the  tedious  business  of  note  taking, 
ensures  that  nothing  is  missed,  and  allows  10, 
the  writer/ interviewer  to  listen  in  detail 
to  what  is  being  said.    The  technical  writer 
announces  each  rubric  from  the  Standard  out-  11, 
line  by  name  and  number  prior  to  the  dis- 
cussion of  the  topic  so  that  the  tapes  are 
automatically  organized  into  the  format  of 
the  final  written  product,  and  a  rough  form 


First  Draft  Typing 
Content  Review 

1st  QA  Review 

Draft  Revision 

Revision  Typing 

Proof  Revisions 

1st  Del i very  to 
Client 

Revisions  Per 
CI ient 

2nd  QA  Review 


Secretary 

Systems 
Staffer 

QA/Document- 
ation  Manager 

Tech  Writer 

Secretary 

Tech  Writer 

Tech  Writer 

Tech  Writer 


QA/Document- 
ation  Manager 
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12.  Revision  Secretary 
Typing/ proofing 

13.  Final  Delivery  Tech  Writer. 

This  sequential,  breakdown  of  the  pro- 
cess formed  the  basis  for  the  system  of  man- 
agement controls  devised  to  guide  the  pro- 
duction of  documents.  Only  two  forms  are 
needed  for  management  control.  The  first  is 
the  "DOCS  PLAN",  (see  the  figure).  This 
form  is  used  for;  estimating,  production 
scheduling,  production  tracking,  and  cost 
statistics  recording.  Space  is  provided  at 
the  top  of  the  form  for  recording  qualita- 
tive parameters  of  the  system  being  documen- 
ted. The  second  form  needed  is  a  simple 
calendar  resource  matrix  arraying  each  tech- 
nical writer  and  other  production  resources 
versus  the  business  date.  The  calendar 
matrix  is  used  to  allocate  technical  writer 
staff  time  to  projects  in  process. 

A  DOCS  PLAN  form  is  kept  for  each 
project  and  has  space  for  the  ten  FIPS  38 
manuals  as  well  as  a  Task  Management  Plan, 
and  non-standard  documents,  for  example 
proposals.  One  calendar  resource  matrix  is 
kept  for  the  technical  writing  group  as  a 
whole  for  all  work  in  process.  The  calendar 
resource  matrix  is  the  integrating  control 
mechanism  by  which  the  writing  activities 
for  many  separate  projects  are  coordinated. 
Maximizing  the  use  of  resources  requires 
that  project  scheduling  be  coordinated 
across  all  projects.  Production  schedules 
are  prepared  as  many  months  in  advance  as  is 
necessary  for  demand  to  allow  for  proper 
workload  planning,  and  staff  recruiting. 

Use  of  the  DOCS  PLAN  form  allows  the 
compilation  of  reliable  statistics  on  the 
resources  required  for  each  set  of  manuals. 
These  statistics  have  been  very  useful  in 
the  preparation  of  documentation  cost  est- 
imates, and  in  production  scheduling.  No 
project  that  has  ever  been  processed  using 
these  methods  has  ever  exceeded  its  budget 
or  missed  even  a  single,  intermediate  step 
production  date,  much  less  a  client  deliv- 
erable date.  This  can  be  attributed  to 
copies  of  the  production  schedule  being 
provided  to  the  persons  who  were  to  be  held 
responsible  for  each  step.  The  due  dates 
established  are  for  small  steps  that  are 
individually  coordinated  with  the  person's 
other  activities,  and  the  staff  hours 
allowed  for  each  activity  are  based  on  well 
accepted  empirical  data.  Further,  each 
individual  in  the  production  process  is 
asked  to  review  the  production  schedule  for 


reasonableness,  and  is  qiven  the  opportunity 
to  request  revisions  in  the  schedule  prior 
to  being  held  responsible  for  it. 

Project  production  scheduling  has  been 
found  to  be  facilitated  by  early  participa- 
tion of  the  technical  writing  staff  and  man- 
agement in  each  systems  project.  Where  re- 
sources for  technical  writing  are  constrain- 
ed by  staff  limitations,  and  there  are  many 
projects  competing  for  those  resources  then 
"1st  day"  participation  by  the  documentation 
manager  is  indispensable  to  smooth  opera- 
tions. 

3.4  Quality  Review  and  Rewrite: 

Reference  to  the  production  steps 
shown  above  reveals  that  six  of  the  thirteen 
steps  are  quality  assurance  in  nature.  Re- 
views are  performed  by  the  project  systems 
staff,  the  QA/Documentation  manager,  the 
technical  writers  and  the  client.  During 
each  review  rewrite  occurs.  This  rewrite  is 
performed  only  by  the  writing  staff  based  on 
marginal  comments  by  reviewers.  This  is  in 
recognition  of  our  premise  to  specialize 
staff  roles,  and  on  negative  experiences 
with  having  the  systems  staffers  attempting 
to  perform  rewrite.  During  its  lifetime  the 
technical  writing  group  has  never  had  a 
manual  rejected  by  a  client,  nor  even  had 
any  serious  negative  comments. 

During  the  training  of  our  technical 
writers  we  communicate  that  rewrite  will 
always  occur  and  that  it  should  not  be  con- 
sidered as  being  critical  or  threatening  in 
nature.  Rewrite  is  viewed  instead  as  being 
a  part  of  the  necessary  process  of  corporate 
writing. 

3.5  Transition  Activities: 

The  documentation  group  did  not  come 
into  existence  immediately  after  the  writing 
of  the  memorandum  that  suggested  the  effi- 
cacy of  creating  such  a  group.  Nor  did  the 
operational  procedures,  the  concepts  under- 
lying the  procedures,  or  an  understanding  of 
how  the  Standard  would  shape  the  evolution 
of  these  things.  In  this  section  we  will 
describe  how  the  documentation  group  grew  up 
and  transitioned  from  pre-group  approaches 
into  something  capable  of  producing  good 
quality,  FIPS  38  manuals,  in  a  manner  akin 
to  an  automobile  assembly  line. 

Higher  management  made  no  objection  to 
the  foundational  proposition,  but  expressed 
skepticism  about  the  ability  of  third  party 
technical  writers  to  document  systems  that 
they  had  not  programmed  themselves.     It  was 
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a  subtle  but  important  point  that  higher 
management  allowed  the  technical  writing 
group  to  form,  but  did  not  make  a  clear, 
affirmative  decision  to  do  so,  nor  did  they 
provide  aggressive  support  in  the  intra- 
company  growing  pains  that  arose  as  the 
writing  group  developed.  This  caused  un- 
necessary and  exaggerated  difficulties  with 
other  managers.  It  was  only  much  later  (6 
to  8  months)  that  higher  management  gave 
recognition  to  the  formation  of  the  writing 
group  as  a  key  factor  in  achieving  a  turn- 
around in  issues  of  systems  quality  and 
client  satisfaction;  as  well  as  an  order  of 
magnitude  decrease  in  systems  development 
problems. 

Substantial  care  was  taken  in  the  pro- 
cess of  recruiting  the  technical  writing 
staff.  Many  more  applicants  were  inter- 
viewed than  the  number  of  available  posi- 
tions. We  recruited  over  a  period  of  sever- 
al months  in  response  to  our  mid  term  sched- 
uling needs  as  indicated  by  our  resource 
matrix.  All  applicants  were  required  to 
submit  writing  samples  as  a  demonstration  of 
their  ability.  The  writing  sample  was  the 
most  important  aspect  of  the  screening 
process.  We  found  that  any  form  of  writing; 
school  papers,  letters  to  the  editor,  etc. 
were  adequate  to  guage  the  applicant's  writ- 
ing prowess.  Misrepresentation  of  credent- 
ials was  discovered  to  be  common.  Once  an 
applicant  had  passed  initial  screenings  all 
references  were  carefully  verified. 

The  group  was  small  enough  to  allow 
for  individual  daily  counselling  on  writing 
style,  systems  concepts,  rubric  definitions, 
and  production  procedures.  Formal  classroom 
sessions  were  held  infrequently  due  to  pro- 
duction needs,  and  were  confined  to  funda- 
mental computer  science  concepts.  The 
learning  curve  was  rapid  for  the  people  we 
selected.  All  were  productive  within  a  two 
week  time  frame.  Three  months  of  experience 
was  enough  for  each  writer  to  perform  the 
role  with  full  independence  and  productiv- 
ity. 

4.  FIPS  PUB  RECOMMENDATIONS: 

Daily  experience  with  FIPS  PUB  38  and 
its  derivative,  DOE  78-6,  leads  us  to  make 
several  recommendations  concerning  the  prag- 
matic aspects  of  using  standards.  Stand- 
ards, if  they  are  to  be  living  things,  used 
broadly  and  thus  serving  their  purpose,  must 
be  proletarian  in  approach,  not  lofty  and 
understandable  only  by  those  with  ten  year 
DP  backgrounds  and  advanced  degrees.  They 
must  also  be  flexible  enough  to  serve  a 
broad  range  of  applications.    And,  they  must 


be  exDlicit,  or  perhaps  it  would  be  better 
to  say  that  they  should  have  a  minimal 
amount  of  vagueness  that  gets  in  the  way  of 
ordinary  folk  trying  to  use  t^em. 

4.1  Proletarian  Useability: 
Provide  a  Tutorial ; 
Improve  Rubric  Definitions: 

We  found  that  having  been  mandated 
with  the  use  of  the  78-6  Standard  we  only 
had  available  a  copy  of  FIPS  PUB  38,  and  a 
copy  of  the  78-6  Standard  (which  had  been 
retyped  by  DOE  EIA  from  FIPS  PUB  38)  upon 
which  to  base  our  actions.  We  had  to  estab- 
lish for  ourselves  how  the  Standard  was  to 
be  related  to  the  production  of  documenta- 
tion. Our  early  experience  showed  that  it 
was  insufficient  to  merely  hand  a  potential 
author  a  copy  of  the  Standard  and  command 
the  creation  of  a  set  of  manuals.  We  pain- 
fully learned  that  even  very  capable  writers 
were  incapable  of  employing  the  Standard 
without  the  benefit  of  daily  training  and 
guidance  in  its  interpretation,  and  in  its 
implied  process. 

The  most  frequent  question  asked  by 
our  writers  during  the  initial  months  was, 
"What  does  this  rubric  mean?"  Sometimes 
even  the  long  term  DP  veterans  who  were 
managing  the  technical  writing  group  found 
this  very  hard  to  answer.  In  the  process  of 
providing  the  answers  to  our  staff's  ques- 
tions it  is  clear  that  we  were  redefining 
the  Standard  for  the  exigency  of  the  moment. 
I.e.,  we  were  confronted  with  the  situation 
of  not  what  does  the  Standard  mean,  but 
rather  what  did  we  say  that  it  meant.  Sub- 
stantial amounts  of  personnel  dollars  were 
involved,  and  firm  decisions  had  to  be  made 
concerning  the  Standard's  requirements,  or 
else  we  would  have  suffered  the  costs  that 
vagueness  directly  created  in  additional 
rewrite  and  reduced  quality  of  written  com- 
munication. 

We  see  this  as  a  flaw  in  the  Guide- 
line, not  as  an  aspect  related  to  its 
attempted  flexibility.  We  found  the  Stand- 
ard to  be  very  hard  to  use,  and  it  is  clear 
that  this  causes  it  not  to  be  used  as  widely 
as  it  might.  We  would  not  have  used  it  had 
we  not  been  contractually  required  to  do  so. 
We  would  have  devised  our  own  outlines. 

This  leads  us  to  make  two  recommend- 
ations on  the  point  of  usability;  (1) 
provide  a  tutorial  as  a  supplement  to  FIPS 
PUB  38  containing  recommended  guidelines  on 
the  use  of  the  Guideline  in  the  production 
process  of  preparing  manuals;  and  (2)  pro- 
vide improvement  in  the  definitions  of  the 
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rubrics  in  the  Guideline  itself  (better  dev- 
eloped, more  elaborate,  and  more  clearly 
worded).  It  is  clear  that  the  writers  of 
FIPS  PUB  38  went  too  far  in  the  direction  of 
flexibility  and  generality  at  the  expense  of 
useable  clarity. 

4.2  Redundancy: 

FIPS  PUB  38  describes  a  ten  manual 
set.  Much  of  the  material  in  this  set  is 
redundant;  e.g.  the  general  information 
sections,  much  of  the  data  base  description 
material,  and  other  information  is  common  in 
all  manuals  of  the  set,  or  is  found  under 
many  rubrics.  This  is  inappropriate  for 
most  application  systems  of  small  and  mod- 
erate size  (i.e.,  the  vast  lion's  share  of 
the  project  count).  This  tends  to  encourage 
"xerox  machine"  authorship  which  contributes 
nothing  to  the  usefulness  of  documentation. 

The  Guideline  should  be  revised  to 
permit,  as  an  option  for  more  modest  sys- 
tems, that  the  ten  manuals  be  considered  as 
chapters  in  a  single  manual  wherein  the  mat- 
erial which  is  now  redundant  would  appear 
only  once.  An  alternative  outline  should  be 
given  as  a  second  part  to  the  Guideline 
which  shows  the  rubrics  for  a  single  manual 
documentation  approach  with  chapters  that 
correspond  to  the  concepts  for  each  of  the 
current  manuals  in  the  Guideline.  This 
would  have  the  effect  of  encouraging  the 
application  of  the  Guideline  to  smaller 
systems  with  a  concomitant  reduction  in  the 
cost  of  documentation. 

4.3  Documenting  Interactive  Systems: 

We  have  found  that  the  current  version 
of  the  FIPS  PUB  38  Guideline  is  very  awkward 
for  use  in  documenting  systems  which  are 
partially  or  wholly  interactive  in  nature. 
FIPS  PUB  38  has  a  consistent  batch  flavor 
throughout  notwithstanding  that  specific 
references  to  batch  processing  are  not 
found.  We  recommend  that  the  Guideline  be 
revised  with  a  view  towards  the  interactive 
systems  case. 

4.4  Propagation  of  the  Guideline 

In  addition  to  the  comments  on  the 
content  of  the  Guidelines  our  experience 
leads  us  to  make  recommendations  concerning 
the  establishment,  propagation,  and  use  of 
the  next  generation  of  the  Guidelines.  The 
new  guidelines  will  be  at  least  as  much  an 
act  of  innovation  as  it  will  be  one  of  codi- 
fying existing  practices;  as  much  a  problem 
of  technology  transfer  as  one  of  regulation. 
The  use  of  the  new  guideline  will  become  a 


contractual  reouirement  for  a  very  Tarqe 
segment  of  the  systems  industry  and  there- 
fore carries  substantial  cost  implications 
for  the  government  if  these  aspects  are  not 
addressed  in  the  guideline  itself. 

Accordingly,  the  establishment  of  the 
next  generation  of  FIPS  documentation  guide- 
lines will  not  (we  think),  consist  of  adopt- 
ing an  existing  standard  as  was  FIPS  PUB  38. 
Since  significant  innovation  must  necessar- 
ily be  involved,  consideration  should  be 
given  to  prototyping,  trial-use  periods, 
major  experimental  application  work,  beta 
testing,  or  other  such  methods  in  addition 
to  the  normal  draft,  review  and  ballot  pro- 
cess. We  in  the  computing  profession  should 
be  aware  that  it  is  very  difficult  to  get  a 
major  product  correct  the  first  time  it  is 
released.  Actual  performance  may  frequently 
vary  from  our  expectations  in  surprising 
ways.  It  is  therefore  appropriate  to  anti- 
cipate a  review  and  rewrite  cycle  for  the 
new  guidel ine. 

Propagation  of  the  .new  guideline 
should  not  consist  simply  of  publication, 
and  an  introductory  workshop,  but  should 
include  a  broader  range  of  technology 
transfer  aids  over  the  lifetime  of  the 
guideline.  Our  experience  does  not  point  to 
all  the  things  that  should  be  done,  but  it 
does  point  to  a  number  of  needs  and  suggests 
a  partial  set  of  answers. 

Among  the  types  of  introductory 
assistance  that  a  guideline  needs  are;  ini- 
tial demonstrations  of  feasibility,  detailed 
explanations  of  the  guideline,  and  particu- 
larly examples.  One  such  approach  is  found 
in  the  IEEE  Atlas  Language  Standard  and  its 
accompanying  book  of  good  practices. 
Another  example  may  be  seen  in  the  "systems 
development  methodologies"  offered  by  some 
commercial  documentation  products. 

A  key  point  of  our  experience  is  that 
a  set  of  rubrics  with  content  definitions  is 
not  enough  no  matter  how  clearly  written 
they  may  be.  Guidance  is  needed  on  all  the 
essential  components  of  documentation  pro- 
duction including;  process,  planning  and 
control,  estimation,  and  quality  assurance. 
All  of  our  recommendations  point  to  a  need 
for  an  expansion  of  the  products  and  serv- 
ices provided  by  NBS  if  good  documentation 
is  to  be  a  normal  occurrence  rather  than  an 
exception. 


151 


NBS  FIPS  Software  Documentation  Workshop,  March  3,  1982 


An  Overview  of  the  Department  of  Defense 
Automated  Data  Systems  Documentation  Standards- 
an  Adaptable  Standard 

Robert  R.  Hegland 

Department  of  the  Navy 
NARDAC  WASHINGTON  DC[1] 

This  paper  describes  the  contents  of  the  Department  of  Defense  Automated 
Data  Systems  Documentation  Standards (DoD  Standard  7935 .l-S).     This  standard 
is  currently  being  used  by  the  Army,  Navy,  Air  Force,  several  defense  agencies, 
and  by  the  Organization  of  the  Joint  Chiefs  of  Staff.     A  slightly  different 
earlier  version  served  as  the  point  of  departure  for  a  federal  documentation 
guideline  which  was  published  in  1976.     In  addition  to  describing  the  standard, 
this  paper  will  discuss  some  of  the  management  and  technical  options  that  may 
be  used  while  still  conforming  with  the  standard. 
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1.  INTRODUCTION 

The  Department  of  Defense (DoD)  documentation  standard  [2]  is  widely  used,  has  a  proven 
successful  record  of  use,  and  is  flexible  enough  to  be  used  across  the  wide  range  of  hard- 
ware and  software  types  used  in  DoD.     The  last  printing,  to  satisfy  specific  user  requests, 
was  for  over  35,000  copies.     It  is  used  by  Army,  Navy,  Air  Force,  Marine  Corps,  the  Office 
of  the  Joint  Chiefs  of  Staff,  the  DoD  agencies  and  also  by  the  contractors  that  support 
them  in  various  development  efforts.     It  was  intended  for  the  documentation  of  management 
information  systems  but  has  been  successfully  applied  to  other  types  of  systems.  Many 
federal  and  commercial  organizations  have  also  obtained  copies.     It  is  used  for  documenting 
large  and  small  systems.     It  is  used  for  documenting  systems  installed  at  only  one  site  and 
those  installed  at  many  sites. 

2.  BACKGROUND 

2.1  Need  for  a  Standard 

When  the  predecessor  of  this  standard  was  developed  in  the  mid  1960's,  it  was  to 
satisfy  the  requirements  of  an  environment  where  several  different  computer  sites  were  to 
receive  the  same  software  but  each  site  wanted  different  documentation  delivered  with  the 
software.     Since  this  documentation  would  have  been  very  expensive  to  develop  and  to 
maintain,  a  decision  was  made  to  develop  a  standard  that  would  satisfy  the  information 
requirements  of  the  different  sites  but  would  also  allow  the  users  sufficient  flexibility 
to  satisfy  their  actual  unique  needs  that  had  originally  caused  them  to  request  different 
documentation.     During  the  development  of  that  standard  and  throughout  the  several  revisions 
to  it,  there  have  been  several  principles  that  have  been  followed  by  the  people  involved  in 
maintaining  it.     Some  of  these  are  listed  below. 

a.  Necessary  user  extensions  of  the  information  to  be  documented  must  be  allowed. 

b.  The  management  options  and  types  of  flexibility  that  a  user  of  the  standard  can 
exercise  in  adapting  the  standard  to  a  particular  environment  while  still  meeting  the  intent 
of  the  standard  should  be  discussed  in  the  standard. 

c.  There  should  be  enough  information  detailed  in  the  standard  to  give  the  person  who 
is  trying  to  follow  the  standard  a  good  understanding  of  what  the  document  should  contain. 
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d.  The  standard  should  not  use  terms  or  phrases  that  are  unique  to  current  philosophy 
or  techniques,  such  as  structured  programming,  top-down  design. 

e.  The  standard  must  not  be  limited  to  specific  hardware  or  software. 

f.  The  use  of  computers  or  word-processing  equipment  to  produce  the  documentation 
should  neither  be  required  nor  prohibited. 

g.  Locally-developed  forms  should  be  allowed. 

2.2  Terminology 

There  are  three  terms  that  are  used  herein  that  need  a  brief  explanation.     A  "project" 
is  considered  to  be  a  development  effort  that  begins  with  the  identification  of  a  need  to 
write  a  computer  program,  such  as  a  payroll  system,  and  extends  through  the  necessary 
analysis  and  design  to  programming,  testing  and  placing  the  program  into  an  operational 
environment.     The  size  of  a  "project"  varies  widely  but  the  standard  discusses  a  way  to 
determine  how  much  documentation  is  needed  for  projects  of  different  sizes.     The  standard 
outlines  ten  "docioment  types"  that  specify  what    "object    documents"  should  contain.  The 
"document  type"  is  one  of  the  ten  documents  outlined  in  the  standard,  such  as  a  Users  Manual 
or  Program  Specification.     An  "object  document"  is  a  document  that  describes  a  particular 
project  and  discusses  how,  for  example,  the  payroll  system  is  to  be  designed (Program 
Specification)  or  how  the  user  is  to  use  the  payroll  system(Users  Manual). 

2.3  Development  of  the  Standard 

This  standard  was  developed  initially  to  serve  a  limited  but  diverse  audience.  Subse- 
quently, others  beyond  that  audience  found  that  they  could  also  use  it.     Copies  were  made 
available  to  many  organizations  and  groups  and  eventually  a  modified  version  became  a  DoD 
standard.     At  each  step  during  the  development  process  different  committees  reviewed  the 
standard  and  made  changes  to  ensure  that  it  would  be  useful  to  the  groups  that  they  repre- 
sented.    While  it  has  not  lost  its  original  integrity,  it  has  been  improved  by  the  contri- 
butions of  each  of  the  people  who  have  been  involved  in  its  development.     It  also  has 
provided  the  basis  for  several  other  uses.     One  individual  copied  large  parts  of  it,  added 
some  other  information,  and  published  it  as  a  paperback  documentation  standard.     It  was 
also  the  primary  point  of  departure  for  the  development  of  the  NBS  FIPS  Pub  38  [3]  that 
was  adopted  as  a  federal  guideline  in  1976.     FIPS  Pub  38  has  the  same  document  types  but 
their  description  has  been  condensed.     Essentially  the  same  life-cycle  example  is  also  used. 
In  addition  to  the  evolutionary  modifications  that  occurred  as  the  standard  was  adopted  by 
different  groups,  there  is  a  DoD  task  group  charged  with  responsibility  for  reviewing  and 
improving  the  standard  as  well  as  with  responding  to  any  reported  problems  in  its  use.  In 
other  words,  this  is  a  dynamic  standard  that  is  maintained  to  keep  up  with  the  state-of-the- 
art  while  not  limiting  it  to  any  particular  group  of  users. 

3.   STRUCTURE  OF  THE  STANDARD 

The  standard  is  a  relatively  small  document  of  about  150  pages  and  is  prepared  using  a 
standard  typing  format  rather  than  by  typesetting  so  that  it  looks  like  the  object  documents 
that  will  be  produced  from  using  the  standard.     This  makes  the  writing  process  somewhat 
easier  for  the  authors  of  the  object  documents.     The  standard  is  made  up  of  three  parts 
which  include  the  information  described  in  the  following  paragraphs. 

3.1  Part  1-General 

This  part  Includes  short  sections  on  the  purpose,  scope  and  objectives  of  the  standard 
as  well  as  a  description  of  its  organization. 

3.2  Part  2-Document  Development  Guidelines 

This  part  includes  a  discussion  of  how  the  standard  is  intended  to  be  used,  how  to  plan 
the  preparation  of  documentation,  and  other  items  that  the  manager  of  a  development  effort 
should  know  about  the  standard  and  about  documentation  in  general  before  writing  the  first 
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word  of  an  object  document.     This  part  also  includes  a  discussion  of  how  the  various  stan- 
dard document  types  can  relate  to  the  development  life  cycle  of  an  application  development 
effort.     The  example  of  a  life  cycle  that  is  included  is  generalized,  is  not  a  standard 
itself,  and  is  shown  for  illustrative  purposes  only.     A  discussion  of  the  purpose* and 
general  contents  of  each  of  the  different  document  types  is  then  presented.     There  is  also 
a  discussion  of  the  options  that  need  to  be  considered  in  using  the  standard.  These 
include  the  relationship  of  project  complexity  to  the  document  types  needed  to  support  a 
particular  development  effort,  how  to  measure  project  complexity,  and  how  to  decide  which 
of  the  ten  document  types  are  needed  for  that  project;  the  sizing  of  documents  and  the 
sections  within  each  document  type;  how  to  tailor  the  document  types  for  specific  imple- 
mentations by  the  addition  or  deletion  of  paragraphs,  sections,  and  other  information  that 
is  called  for  in  the  standard;  and  the  use  of  graphic  charts  and  forms. 

3.3  Part  3-Docuraent  Standards 

This  part  of  the  standard  includes  the  ten  different  document  types.     Each  document 
type  is  presented  in  a  way  that  allows  it  to  be  removed  from  the  overall  standard  for  use 
by  the  person  or  group  preparing  the  object  document.     The  paragraph  numbers  and  titles  in 
each  document  type  are  exactly  as  they  should  be  in  the  object  document  except  as  may  be 
modified  by  the  application  of  an  allowable  management  option.     Within  each  of  the  para- 
graphs is  a  detailed  narrative  description  of  the  type  of  information  that  should  be 
included  in  the  object  document.     Many  of  the  paragraphs  in  the  document  types  also  have 
"shopping  lists"  of  items  that  may  be  appropriate  to  discuss  in  the  related  paragraph  of 
the  object  document.     That  document  may  present  the  required  information  in  a  narrative, 
in  a  figure,  or  on  a  form.     If  a  figure  or  form  is  used,  the  standard  paragraph  number  and 
title  must  be  used  but  the  short  narrative  text  can  simply  refer  to  the  appropriate  figure 
or  form.     In  a  few  cases  there  are  examples  of  figures  that  can  be  used  to  support  the  text 
but  these  usually  are  avoided  in  the  standard  since  most  sites  have  their  own  forms  or 
their  own  techniques  for  presenting  figures. 

4.  USING  THE  STANDARD 

4.1  The  Document  Types  and  Life  Cycle 

Figure  1  shows  a  generalized  life  cycle  and  how  the  ten  document  types  in  the  standard 
relate  to  the  phases  and  stages  shown.     The  transition  from  one  phase  to  another  is  usually 
not  as  sharply  defined  as  might  be  interpreted  from  the  figure.     The  purpose  of  the  document 
types  should  be  apparent  from  their  placement  in  the  life  cycle  and  from  their  titles.  Even 
though  the  standard  specifies  the  contents  of  ten  document  types,  all  ten  are  seldom 
produced  on  a  project.     The  number  of  document  types  needed  to  support  the  development 
effort  depends  on  the  complexity  of  the  project,  on  the  experience  level  of  the  developers 
and  users,  on  whether  or  not  the  developers  have  worked  in  the  application  area  where  the 
program  is  to  be  developed,  and  on  other  managerial  and  technical  considerations. 
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Figure  1.  The  ADS  Development  Life  Cycle  Related  to  Document  Preparation  and  Use. 
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4.2  Project  Complexity  and  Document  Types 


The  standard  provides  a  guideline  for  determining  what  documents  may  be  needed  for  a 
particular  project.     There  are  12  factors  listed  including  span  of  operation,  criticality, 
and  programming  languages  used.     Each  has  a  possible  weight  of  from  l(for  a  weight  indi- 
cating limited  or  easy)   to  5 (for  extensive  or  hard).     When  the  assigned  weights  from  1  to 
5  are  added  up  for  each  of  the  12  factors,  the  total  is  used  to  enter  a  table  that  shows 
which  document  types  should  be  written  for  that  project.     For  most  projects  of  an  "average" 
size  and  complexity  five  object  documents  are  usually  prepared.     The  developmental  environ- 
ment may  allow  fewer  or  may  require  more.     This  is  a  very  generalized  guideline  to  which 
good  technical  and  management  judgment  must  be  applied  before  deciding  what  document  types 
will  actually  be  written. 

4.3  Audience 

Different  sites  sometimes  feel  that  their  organization  is  unique  and  so  can't  use 
standard  documentation.     For  example,  at  some  sites  data  retrievals  are  performed  by  a 
manager  from  a  terminal  in  the  working  area;  at  other  sites  the  retrievals  may  be  made 
by  a  maintenance  programmer.     The  basic  retrieval  set-up  for  the  manager  might  be  in  a 
manager's  handbook  at  one  site  and  in  a  maintenance  manual  at  the  other  site.  Such 
arbitrary  structures  would  obviously  make  a  standard  impossible.     To  avoid  the  problem  and 
encourage  standards,   the  DoD  standard  is  oriented  toward  satisfying  the  audience  by  the 
function  that  the  audience  is  performing.     Regardless  of  whether  the  retrieval  is.  being 
executed  by  a  manager,  a  programmer,  or  by  a  computer  operator,  the  function  being  per- 
formed is  one  of  a  user  of  the  data  and  should  therefore  be  documented  in  a  Users  Manual. 

4.4  Redundancy 

Redundancy  is  a  much  discussed  topic  in  writing  documentation  standards.  DoD  users 
have  performed  studies  on  the  DoD  standard  to  identify  any  unnecessary  redundancy  and  have 
found  little.  What  is  necessary  redundancy?  One  type  is  the  introductory  material  needed 
to  identify  the  purpose  of  the  system,  list  related  documentation,  etc.  That  information 
serves  as  "boilerplate"  for  each  object  document.  Other  types  of  necessary  redundancy  are 
"apparent  redundancy"  and  "evolutionary  redundancy"  both  of  which  are  discussed  in  the  DoD 
standard  and  which  are  not  undesirable  if  handled  properly. 

Apparent  redundancy  occurs  when  two  document  types  discuss  what  appears  to  be  the  same 
information,   such  as  "input"  which  is  discussed  in  both  the  Users  Manual  and  the  Computer 
Operation  Manual.     The  information  included  in  the  object  document  should,  however,  be 
different  for  each  audience.     The  user  needs  information  about  the  structuring  of  the  data 
input  while  the  operator  needs  to  know  how  many  card  decks  and  tapes  to  use. 

Since  project  development  can  cover  a  long  period  ot  time,   the  standard  allows  for 
including  information  that  has  changed  since  the  last  document  was  published.     For  example, 
there  may  have  been  new  equipment  acquired  that  must  be  discussed  in  a  paragraph  dealing 
with  environment  since  the  original,  planned  description  of  the  environment  in  the 
Functional  Description.     If  there  has  been  no  change  to  something  that  has  already  been 
documented  and  if  that  document  is  available  to  all  recipients  of  the  new,  updated 
document,   the  paragraph  can  simply  refer  back  to  the  older  document  for  the  information 
that  is  still  current. 

4.5  Document  Sizing 

The  standard  provides  some  guidance  to  the  authors  of  object  documents  in  terms  of 
planning  the  overall  size  of  object  documents.     The  standard  can  be  used  to  write  an  object 
document  of  any  document  type  that  might  be  100  pages  or  500  pages  in  length  and  both  might 
conform  to  the  standard.     The  manager  of  the  project  development  effort  must  make  it  clear 
to  the  development  staff  whether  a  large  or  small  document  is  to  be  written.     The  tendency 
to  overdocument  can  be  just  as  bad  and  as  expensive  as  the  tendency  to  underdocument .  In 
addition,  the  standard  specifies  the  approximate  percentage  relationship  of  each  of  the 
sections  in  the  document  to  the  overall  page  total  of  that  document.     This  is  only  a 
general  guide  but  does  help  to  establish  what  sections  of  each  document  type  need  to  have 
the  primary  emphasis. 
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5.  CONCLUSION 


Much  work  has  been  done  in  recent  years  on  documentation  standards.     The  DoD  standard, 
from  its  high  degree  of  acceptance,  seems  to  have  bridged  the  gap  between  undue  rigidity 
and  a  totally  flexible  standard.     It  has  proven  itself  to  be  an  adaptable  standard  that  can 
be  modified  by  local  managers  to  meet  their  needs,  is  maintained  by  a  committee  responsive 
to  general  user  needs,  but  is  still  a  standard  that  provides  a  useful  structure  to  authors 
of  technical  documents.     As  more  tutorial  and  menu  selection  systems  are  written,  the 
standards  will  need  to  be  reviewed  to  ensure  that  these  design  philosophies  can  be  accommo- 
dated in  the  existing  structure  or  the  structure  will  have  to  be  modified  to  allow  for  them. 
There  is  still  a  need  to  provide  the  many  audiences  of  the  documentation  of  a  project  with 
object  documentation  that  is  concise  and  useful  in  helping  them  perform  their  functions  and 
with  documentation  that  will  support  the  sharing  of  software. 
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NBS  FIPS  Software  Documentation  Workshop,  March  3,  1982 

SESSION  D:    Do  Existing  Standards  Work? 
Elizabeth  C.  Weinberger 
U.S.  Department  of  Health  and  Human  Services 
Summary 


Although  documentation  standards  exist  (i.e.,  FIPS  PUBs  38  and  64),  there  are  inade- 
quacies within  the  standards,  problems  with  the  way  the  standards  are  applied,  and  often 
a  failure  to  use  the  standards.    In  this  session,  the  panelists  and  audience  discussed 
various  problems  with  documentation  and  several  ways  to  reduce  such  problems. 

Ronald  Thies  began  with  a  discussion  of  one  inadequacy  of  the  current  standards  which  do 
not  contain  sufficient  security  documentation.    Due  to  the  increased  emphasis  on  security, 
particilarly  with  the  issuance  of  0MB  Circular  A-71 ,  there  is  a  need  for  specific  security 
documentation  to  be  included  throughout  the  system's  life  cycle.    Mr.  Thies'  presentation, 
"Documenting  Systems  Security,"  included  detailed  examples  of  security  provisions  to  be 
ad^ed  at  four  different  stages  of  documentation:    1)    Functional  Requirements  Document, 
2)    System/Subsystems  Specification,  3)    Test  Plan,  and  4)    Test  Analysis  Report, 

The  audience  raised  a  significant  question  about  the  potential  danger  of  detailing  the 
system's  vulnerable  points  and  identifying  the  safeguards  for  each  of  these  vulnerable 
points.    This  practice  could  result  in  system  abuse  or  misuse.    The  audience  suggested  that 
detailed  security  documentation  have  a  very  limited  distribution.    Mr.  Thies  said  this 
isn't  such  a  problem,  because  although  the  vulnerable  points  and  safeguards  are  identified 
in  the  security  documentation,  the  specifics  of  each  safeguard  are  not  provided.  For 
example,  if  a  certain  vulnerable  point  in  the  system  required  a  code  to  be  entered  as  the 
safeguard,  the  actual  code  would  not  be  part  of  the  documentation. 

The  second  presentation,  "Using  FIPS  PUB  38:    A  Practical  Experience,"  related  how  a  change 
in  the  documentation  process,  while  using  the  existing  standards,  greatly  improved  the 
quality  and  timeliness  of  systems  documentation.    Patrick  0'  Connor  and  Samuel  Redwine,  Jr. 
were  both  employed  by  a  particular  company  which  was  experiencing  poor  documentation 
products,  programmer  resistance  to  doing  documentation,  management  concern  over  using 
expensive  data  processing  personnel  to  write  documentation  rather  than  do  more  programming, 
and  problems  in  meeting  schedules  and  budget  restraints. 

The  solution  was  relatively  simple.    After  a  major  crisis  which  required  a  complete  re- 
writing of  documentation  in  an  extremely  short  period  of  time,  the  company's  top  management 
realized  the  importance  of  doing  good  documentation  and  raised  it  as  a  priority.    They  then 
decided  to  relieve  the  system  staff  of  this  burden  and  created  a  division  of  labor.  "Let 
systems  staff  build  systems,  and  let  writers  write  documentation."    The  company  hired  a 
technical  writer  and  later  expanded  by  establishing  a  group  of  technical  writers.  They 
established  a  process  for  documentation  whereby  the  technical  writer  interviewed  the 
systems  staff,  using  a  tape  recorder  and  a  FIPS  38  checklist. 

The  changes  were  dramatic.    The  technical  writers  produced  solid  documentation  products, 
and  were  less  expensive  than  the  data  processing  personnel.    The  success  generated  an 
improved  attitude  about  documentation  and  reinforced  it  as  a  company  priority.  And, 
most  important,  schedules  and  budgets  were  routinely  achieved. 

The  audience  had  many  comments  and  questions  about  using  technical  writers  to  write 
documentation.    Many  commentors  echoed  the  success  of  this  practice,  at  the  Department  of 
Energy  and  the  Navy.    Some  audience  members  believed  the  technical  writers  should  receive 
data  processing/systems  training,  whereas  others  strongly  disagreed,  saying  that  such 
training  was  costly,  time  consuming  and  resulted  in  mid-priced  technical  writers  leaving 
to  seek  higher  paying  data  processing  positions.    The  panelists  were  quite  insistent  that 
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the  only  qualifications  for  a  good  technical  writer  were  to  be  smart,  write  well  and  be 
an  "eager  learner."    This  was  a  key  point  of  the  presentation.    The  panelists  claimed  that 
contrary  to  the  belief  that  a  non-technical  person  can  not  write  such  a  manual,  and  can 
write  it  well  I 

The  final  presentation  by  Robert  Hegland  compared  the  provisions  of  FIPS  38  with  the  Depart- 
Department  of  Defense's  Automated  Data  Systems  Documentation  Standard.    According  to  Mr, 
Hegland,  DOD's  standard  provides  more  descriptive  prose  and  more  examples  of  documentation 
than  what  FIPS  38  provides.    Although  the  DOD  standard  is  quite  useful  as  a  general  purpose 
standard  and  is  flexible  for  the  user,  the  weakness  of  the  standard  is  that  it  does  not 
address  the  newest  technology,  and  does  not  adequately  detail  documentation  of  interactive 
systems. 

In  closing,  the  panelists  and  audience  agreed  that  the  National  Bureau  of  Standards  needs 
to  revise  FIPS  38  to  make  it  more  usable,  clearer,  easier  to  understand,  and  more  of  a 
tutorial  aid.    They  suggest  that  NBS  remove  the  redundancy  within  the  standard,  provide 
examples,  and  detail  the  entire  documentation  process  rather  than  providing  just  an  outline 
of  documents.    The  new  standard  should  be  innovative,  allow  for  prototyping  and  field 
testing,  and  address  documentation  for  interactive  systems. 
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Session  E: 


Proposals  for  Documentation  Standards 


Moderator : 


Trudy  Grieb,  Hadron,  Inc. 


Discussants : 


Edward  W.  Hurley,  Hadron,  Inc. 

Samuel  T.  Redwine,  Jr.,  The  MITRE  Corp. 


Recorder: 


Andrea  F.  Papilion,  Hadron,  Inc. 


Introduction:  In  the  past,  documentation  standards  have  been  of  very  little  net  value  to 
the  audience  of  documentation  (management,  project  leaders  and  project  staff)  and  to  the 
authors  of  documentation.  What  new  approach  is  needed  to  produce  a  new,  better  set  of 
documentation  standards? 

The  papers  in  this  session  proposed  approaches  to  documentation  standards  for  the  purpose  of 
overcoming  problems  encountered  in  using  current  --  often  inconsistent,  sometimes  conflict- 
ing and  awkward  --  documentation  standards. 

The  first  paper.  Proposed  Approach  to  Standards  for  Documentation  of  Projects  and  Systems 
Based  on  Actual  Requirements,  Trudy  Grieb,  Hadron,  Inc.,  provides  an  overview  of  the 
problems  that  need  to  be  addressed  and  possible  approaches  to  solutions. 

The  second  paper,  Microcomputer  Systems  Users  Need  Better  Documentation,  Richard  A.  Bassler, 
The  American  University,  provides  a  discussion  of  problems  and  vital  recommendations  for 
producing  better  documentation  for  microcomputer  users. 

The  third  and  last  paper,  A  Proposed  Documentation  Standard  Based  on  a  System  Decomposition 
and  Information  Base  Approach,  Saul  A.  Zaveler,  U.S.  Air  Force,  provides  an  important 
proposal  to  treat  the  subject  of  documentation  with  the  same  respect  and  the  same  concepts 
of  decomposition  as  those  used  for  the  software  being  developed.  The  paper  also  states  that 
considerations  for  content  should  be  separated  from  considerations  for  format  and 
organization. 


159 


NBS  FIPS  Software  Documentation  Workshop,  March  3,  1982 


Approach  to  Standards  for  Documentation 
of  Projects  and  Systems 
Based  on  Requirements  of  the  Users  of  Documentation 

Trudy  Grieb 

Director,   Information  Systems  Technology 
Hadron  Incorporated 
Vienna,  Va.  22180 

This  paper  addresses  questions  about  and  possible  solutions  for  the  docu- 
mentation of  information  processing  systems  and  the  projects  which  are  the 
vehicles  for  creating  these  systems.  This  paper  (1)  defines  the  problems  and 
requirements  of  the  documentation  of  projects  and  systems;  (2)  evaluates  existing 
attempted  solutions  (i.e.,  current  documentation  standards),  and  (3)  proposes  a 
tested  and  proven  approach  to  new  Federal  Government  documentation  standards 
based  on  actual  requirements. 

Keywords;      documentation    standards,    information   processing   system  standards, 
project  management  standards. 

1.  INTRODUCTION 

In  the  past,  documentation  standards  have  been  useful  to  only  a  small  degree  and  have 
created  unnecessary  problems.  The  purpose  of  this  paper  is  to:  (1)  point  out  the  major 
problems  with  the  past  approaches  to  documentation  standards,  (2)  define  the  general 
requirements  for  documentation  standards,  and  (3)  propose  a  new,  promising  approach  to 
documentation  standards  that  will  be  useful  to  the  readers/users,  to  technical  personnel, 
and  to  managers,  without  creating  unnecessary  problems. 

The  scope  of  this  discussion  includes: 

o    Projects  for  information  processing  systems; 
o    Information  processing  systems; 

o    Documentation    for    users,     line    management,    project    management,    and  technical 
personnel . 

The  intended  audience  of  this  paper  consists  of  senior  level  systems  analysts,  project 
leaders/managers,  standards  analysts/developers,  and  managers,  who  are  responsible  for 
systems  analysis,  development,  and  project  management  personnel. 

2.  PROBLEMS 

Existing  documentation  standards  for  information  processing  systems  are  inadequate  due 
to  a  number  of  major  problems. 

2.1     Lack  of  Context 

All  existing  documentation  standards  are  based  on  an  assumed  and/or  implied  set  of 
concepts  and  System  Life  Cycle  Methodology  (SLCM).  Therefore,  the  assumed  SLCM  is  not 
clear,  and  cannot  be  properly  used  in  the  development  of  a  project  plan  which  should  include 
a  clear  plan  and  definition  of  all  documentation  to  be  produced.  All  documentation  is 
produced  in  the  context  of  a  project  plan,  which  is  usually  different  from  the  one  implied  by 
the  documentation  standard.  The  authors  of  documentation  then  are  forced  to  resolve  the 
conf 1 icts. 


160 


Further,  the  methodologies  implied  by  the  documentation  standards  are  usually  incom- 
plete, unclear,  and/or  incorrect.  Some  of  the  most  common  and  popular  concepts  on  which 
most  methodologies  are  based  are  not  workable. 

As  a  result,  the  current  documentation  standards  do  not  meet  the  requirements  of  the 
readers/users  of  the  final  documents. 

2.2  Awkward  and  Arbitrary  Standards 

Without  a  clear,  complete  SLCM,  the  developers  of  documentation  standards  are  handi- 
capped. They  need  the  SLCM  as  a  context  for  the  development  of  documentation  standards. 
Standards  developed  without  a  SLCM  are  based  on  arbitrary  assumptions  and  are  awkward  to 
fol low. 

2.3  Lack  of  Guidance  and  Definitions 

Most  documentation  standards  do  not  provide  sufficient  explanations  of  what  informa- 
tion is  needed.  Part  of  such  explanations  must  be  the  clear,  complete  definitions  of  terms 
used  in  the  standard.  Another  part  must  be  descriptions  and  examples  of  required  informa- 
tion content. 

2.4  Excessive  Rigidity 

Many  documentation  standards  that  have  been  used  over  the  years  are  very  rigid.  They 
require  strict  outlines,  titles,  headings,  numbering  systems  and  formats.  They  do  not 
permit  adaptation  based  on  the  project  and  system  being  documented.  They  also  tend  to  place 
primary  emphasis  on  format  instead  of  information  content. 


3.  REQUIREMENTS 

The  primary  requirements  of  the  users/readers  of  project  and  system  documentation  are: 

3.1  Control  by  Upper  Management 

Upper  management  must  be  provided  with  necessary  and  sufficient  information  for 
decision-making  and  control. 

3.2  Project  Management 

The  Project  Manager  and  project  team  members  must  have  information  which  will  assist 
them  in  achieving  the  purpose  and  objectives  of  the  project  with  efficiency,  high  produc- 
tivity, and  products  of  high  quality. 

3.3  Progress  Information 

Upper  management,  project  management,  and  the  users  must  have  timely  progress  informa- 
tion about  the  project  and  the  system. 

3.4  Means  of  Communication 

The  Project  Manager  and  project  team  members  must  have  an  effective  means  of  communica- 
tion about  the  project  and  all  components  of  the  system. 

3.5  Quality  and  Productivity 

Upper  management,  project  management,  project  team  members,  and  the  users  need  high- 
quality  products  and  high  levels  of  productivity  as  well  as  cost-effectiveness. 
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3.6  Modern  Technology 

All  personnel  concerned  with  the  project  and  system  need  to  have  the  standards  and 
final  system  (including  documentation)  in  harmony  with  and  responsive  to  modern  technology, 
as  appropriate.  Modern  technology  impacts  all  phases  of  the  system  life  cycle  (SLC), 
including  the  project  management  approach,  the  system,  and  the  production/distribution  of 
documentat  ion. 

3.7  The  User  as  the  Customer 

The  end-users  of  the  system  need  instructions  and  descriptive  information  that  will 
allow  them  to  understand  their  system  and  to  use  it  as  easily  and  effectively  as  possible. 
They  need  to  have  their  documentation  written  and  presented  in  a  form  and  language  that  they 
can  understand  without  having  to  learn  about  computer  and  communications  technology. 

k.  CHARACTERISTICS  AND  RESULTS  OF  GOOD  DOCUMENTATION  STANDARDS 

Useful  and  helpful  documentation  standards  must  have  certain  essential  characteristics 
to  meet  the  requirements  stated  in  Section  3  and  must  avoid  the  problems  stated  in  Section  2. 

^.1     Information  Appropriate  for  Management 

Documentation  standards  should  provide  for  non-technical  summary  documents  which 
crystal  ize  the  major  points  to  be  considered  and  which  state  the  decision(s)  requ-ested  of 
management.  Such  documents  will  allow  management  to  be  informed  and  to  make  timely 
dec  i  s  ions. 

h.2    A  Context  for  Document  Standards 

Documentation  standards  should  be  based  on  a  generic,  functional,  standard  SLCM  which, 
in  turn,  was  designed  to  implement  general  policies  and  to  meet  organizational  objectives 
and  goals.  Such  a  standard  SLCM  provides  the  required  context  now  lacking  and  therefore, 
would  allow  development  of  meaningful,  helpful,  and  easy-to-use  documentation  standards. 

A. 3     Information  for  Progress  Reporting 

Documentation  standards  should  encourage  a  "document-as-you-go"  approach,  rather  than 
after  the  fact.  This  will  allow  information  to  be  captured  as  it  becomes  available  and  at  a 
time  in  which  it  can  meet  most  progress  reporting  requirements.  This  approach  will  also 
provide  for  more  effective  and  reliable  communication  among  project  team  members  in  the 
performance  of  their  work.  As  a  result,  project  team  members  will  be  documenting  for  their 
own  benefit,  as  well  as  for  the  benefit  of  management  and  users. 

h.k    Room  for  Technology 

Documentation  standards  should  reflect  applicable  modern  technology.  Such  standards 
will  encourage,  rather  than  restrict,  the  use  of  modern  technology  in  the  design  of  systems 
and  in  the  production/distribution  of  documentation.  Again,  this  will  increase  productivity 
and  qual i  ty . 

4.5    Appropriate  Documentation  for  End-Users 

Documentation  standards  should  describe,  teach,  and  demonstrate  the  non-technical, 
straight-forward,  user-oriented  presentation  and  language  of  user  documentation.  Because 
very  few  authors  have  produced  practical,  easy-to-understand  user  documentation,  as  much 
guidance  as  is  practical  should  be  included.  The  resulting  increase  in  quality  of  user 
documentation  will  allow  users  increased  effectiveness  of  their  systems  with  less  effort  on 
their  part  in  learning  to  use  them.  In  turn,  this  will  encourage  increased  productivity  and 
decreased  costs  for  the  user. 
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A. 6    Clear  and  Thorough  Explanations 

Documentation  standards  should  provide  clear  and  thorough  explanations  of  the  informa- 
tion requested  and  why  it  is  requested.  Examples  should  be  used  freely.  This  will  (1)  make 
the  standard  easier  to  use,  (2)  will  teach  the  inexperienced  author  what  is  required,  and 
(3)  will  permit  the  standards  to  be  applied  in  a  wide  variety  of  situations  and  projects. 

^.7  Flexibility 

Documentation  standards  should  be  designed  to  be  enforced  at  a  general  level  but  should 
be  flexible  at  a  detailed  level.  The  standards  should  not  impose  an  awkward,  rigid 
structure  on  all  documentation  that  is  to  be  produced. 

5.  CONCLUSION 

The  realm  of  project  management,  SLCM,  procedures,  and  standards  can  be  compared  to  the 
body  of  a  dog.  When  the  documentation  standards  are  the  only  standards/guidelines  that  are 
fully  developed  and  implemented,  "the  tail  is  trying  to  wag  the  dog".  Of  course,  the  dog  has 
great  difficulty  making  progress  this  way.  However,  when  a  SLCM  (including  concepts  and 
terms)  is  defined  and  implemented  in  its  own  context  of  project  management  policies,  the  dog 
has  a  chance.  With  appropriate  procedures  implementing  both  the  SLCM  and  the  documentation 
standards  (and  other  necessary  standards),  the  dog  may  actually  reach  a  pre-defined  goal 
efficiently  and  effectively. 

6.  RECOMMENDATIONS 

The  following  recommendations  are  made  for  the  development  of  documentation  standards. 

6.1  Provide  a  Context 

First,  develop  and  test  a  total  System  Life  Cycle  Methodology  (SLCM)  (including  a 
Glossary  of  Terms)  to  serve  as  the  context  for  documentation  standards.  An  SLCM  defines 
what  processes,  inputs,  and  outputs  are  required  in  a  relatively  complex  project.  Such  a 
context  and  definitions  of  terms  will  minimize  the  usual  conflict  between  what  people  do  to 
perform  their  assigned  tasks  and  the  informat  ion  they  document  about  the  process  they  use 
and  the  output  they  produce. 

6.2  Define  Information 

Second,  develop  and  test  outlines  of  the  k i nd  of  information  required  by  the  users/ 
readers  of  the  documentation.  In  the  context  of  an  SLCM,  it  is  possible  to  develop  and 
distribute  workable  outlines  of  information  required  in  each  written  output.  Feedback  and 
discussions  will  allow  the  authors  of  these  outlines  to  test  and  correct  their  contents  and 
scopes.     Do  not   include  formatting  standards  at  this  point  in  time. 

6.3  Describe  Information 

Third,  develop,  write  and  test  explanations  of  the  information  required  (including  a 
glossary  of  terms)  in  each  part  of  each  required  document.  These  descriptions  must  provide 
useful  guidance  to  the  personnel  who  use  the  standard  to  produce  their  documents. 

6. A    Develop  Criteria 

Next,  develop  evaluation  criteria  to  be  used  in  reviewing  the  final  documents  to  be 
produced  by  all  personnel  who  will  use  the  standards.  These  criteria  (1)  will  inform  the 
authors  what  is  expected,  and  (2)  will  permit  an  objective  review  of  the  final  documents  by 
third  parties  of  the  final  documents. 
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6.5    Develop  Format  Guidelines 


Finally,  develop  standards  for  the  organization  and  format  that  are  required  and/or 
desired  in  the  final  documents.  Again,  this  provides  guidance  to  the  authors  of  the  final 
documents. 

6.6  Justifications 

The  justifications  for  these  recommendations  are  that  documentation  standards 
developed  in  this  manner: 

o  Meet  the  requirements  of  the  users  of  the  standards 

o  Simplify  the  process  of  following  the  standards 

o  Decrease  misunderstandings  and  associated  morale  problems 

o  Increase  productivity 

o  Decrease  costs 

o  Increase  the  quality  of  final  documents. 
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RECORDER'S  COMMENTS 


1.    Approach  to  Standards  for  Documentation  of  Projects  and  Systems,  Based  on  Requirements 
of  the  Users  of  Documentation,  Trudy  Grieb 

1.1  Summary  of  Discussions 

This  paper  presented  a  systems  view  of  documentation,  including  requirements,  goals, 
context,  and  overall  functions.  It  is  important  to  look  both  at  what  the  documentation  is 
doing  now  and  what  it  will  do  in  the  future. 

The  question  was  raised  by  the  discussant  as  to  whether  FIPS  Pub.  38  should  be  revised 
incrementally  or  whether  a  radical  new  approach  should  be  taken.  The  audience  voted  about 
evenly,  but  pointed  out  that  a  middle  ground  might  also  be  effective. 

There  are  three  basic  ways  to  develop  documentation  in  the  context  of  a  system  life  cycle:  a 
thorough  approach  within  the  life  cycle,  prototyping,  and  a  do-it-yourself  by  the  user. 

The  meaning  of  documentation  includes  getting  to  know  what  the  system  is  or  does.  The 
definition  of  documentation  can  range  from  an  extensive  manual  describing  or  instructing  on 
a  system  down  to  the  simple  prompts  of  a  program  or  the  code  itself.  We  need  to  think  in 
terms  of  a  large  scale  view. 

The  object  of  producing  standards  for  documentation  is  to  define  a  content  and  format  that 
will  make  the  user  happier;  but  we  get  little  feedback  from  users  on  what  they  want.  We 
develop  standards  for  people  producing  a  system;  yet  in  the  past  we  didn't  care  how  we  could 
make  their  jobs  more  palatable. 

We  are  looking  at  both  general  project  standards  and  documentation  standards.  Should  these 
kinds  of  documentation  and  standards  be  separated?  We  may  not  know  how  to  produce  general 
standards  for  all  kinds  of  projects.  When  documenting  a  project,  we  want  to  know  about  it 
while  we  are  doing  it.  When  documenting  a  system,  we  need  a  method  of  keeping  the  documenta- 
tion up  to  date  over  the  life  of  the  system. 

1.2  Summary  of  Questions 

•  Q:  How  would  the  speaker  redesign  FIPS  Pub.  38,  and  would  there  be  more  or  fewer 

reports  in  the  index? 

A:  In  redesigning  FIPS  Pub.  38,  a  context  should  be  provided.  The  number  of  reports 
is  not  significant,  but  the  number  of  sections  or  bodies  of  information  available 
at  the  end  of  a  project  or  system  development  is  significant.  The  reports  that 
work  best  for  each  project,  in  harmony  with  the  standards  and  in  context  of  the 
project,  are  the  answer. 

•  Q:  Are  we  talking  about  a  definition  of  a  reasonable  basis  of  theory  of  what 

documentation  should  be? 

A:  Yes.  We  also  need  to  define  concepts  proven  to  work  versus  those  that  are 
popular  but  don't  work.  The  new  standards  should  be  based  on  those  concepts  that 
do  work. 

•  Q&A:   The  speaker  agreed  that  the  development  of  standards  should  be  treated  as  just 

as  much  of  a  project  as  the  development  of  software. 
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A  PropDsed  Docunentation  Standard  Based  on  a 
Syston  Deccmposition  and  Information  Base  ^^proach 


Saul  A.  Zaveler 


Air  Force  Data  Services  Center  [1] 


A  proposal  is  made  for  revision  of  FIPS  38  with  regard  to  viewpoint  and  content. 
The  viewpoint  suggested  is  that  system  deccmposition  (into  components,  functions, 
subsystans,  actions,  or  events)  serve  as  the  principal  basis  of  document  organiza- 
tion, and  that  the  principal  document  types  all  have  similar  informational 
requirements  but  differ  in  degree  of  detail .    Ihe  informational  requirements 
specify  a  data  base  from  vSiich  the  docunents  are  derived.    The  principal  content 
changes  are:    identical  paragraph  nunbering  for  similar  information  in  all  docu- 
ments; provision  for  interactive  systems,  and  provision  for  docunention  of  project 
management  matters. 

REWORDS:    Documentation,  Docunentation  Standards,  Ttop-Down,  System  Deccmposition, 
Software  Engineering,  FADPUG. 

1 .  INTRODUCTION 

1.1  This  paper  proposes  a  replacemeait  for  FIPS  38  [2],  "Guidelines  for  Docunentation  of 
Ccmputer  Programs  cind  Automated  Data  Systems."  The  intent  is  to  revise  FIPS  38  so  that 
it  would  be  better  suited  to  modem  methods  of  system  developnent,  and  to  the  docunenta- 
tion of  interactive  and  real-time  systems. 

1.2  The  Federal  ADP  Users  Groi^,  Special  Interest  Group  on  Standards  and  Quality 
Assurance  (FADPUG/QA)  conducted  a  study,  in  the  suniner  of  1980,  on  the  deficiencies  of 
FIPS  38.    One  result  was  a  skeleton  strawman  standard  vhich  would  serve  as  the  basis  of 
a  revised  FIPS  38.    The  study  was  conducted  at  the  invitation  of  A.  J.  Neunann  of 
NBS/lCST.    The  author  of  this  paper  participated  in  the  study  and  had  a  principal  role 
in  the  formulation  of  the  strawman.    A  discussion  of  the  study  has  been  published  [3]. 

1 . 3  The  author  has  revised  and  developed  the  strawnan  into  an  actual  docunentation 
standard  for  experimental  use  in  his  organization.    This  paper  reports  on  that  standard. 
However,  the  opinions  expressed  in  this  paper  are  those  of  the  author,  and  are  not 
necessarily  those  of  his  employer,  or  of  any  other  component  of  the  U.S.  federal  govern- 
ment. 

1 • 4    The  proposed  standard  covers  the  Functional  Description  ( FD) ,  System/ Subsystem 
Specification  (SS),  Program  Specification  (PS),  Operation  Manual  (OM) ,  User's  Manual 
(UM)  and  Nfeintenance  Manual  (M^) .    It  also  covers  or  references  the  requirements  of  the 
Test  Plan,  Test  Analysis  Report,  Data  Requirements  Docunent,  and  the  Data  Base  ^aecifi- 
cation.     (These  documents  are  defined  in  FIPS  38.)  It  also  provides  for  project 
management  information  and  for  additional  types  of  documents. 

2.  SIJMMARY  OF  RECOMMENDATIONS. 

Revise  FIPS  38  along  the  lines  suggested  by  this  paper  and  the  draft  Docunentation  Stan- 
dard vhich  it  discusses.    System  decomposition  should  be  the  basis  of  organization  of 
all  prescribed  documents.    Information  requirements  should  be  separated  from  information 
display  requirements.    Provision  should  be  made  for  docunentation  of  project  management 
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requir  orients . 

Basis  for  recanmendations :  FIPS  38  is  hostile  to  moraem  methods  of  system  development 
and  to  documentation  of  interactive  systems.  This  observation  is  based  on  personal  and 
organizational  experience  and  on  the  EADPUG/QA  report  cited  above.  The  recanmendations 
vd.ll  obviate  these  problems  in  an  effective  and  enduring  manner  because  they  are  compa- 
tible with  a  wide  variety  of  system  development  methodologies,  yet  do  not  prescribe  any. 
Docunents  produced  from  the  proposed  standard  will  be  more  usable  than  those  prescribed 
by  FIPS  38. 

3.     GENERIC  RECOMMENDATIONS 

The  recanmendations  discussed  below  are  key  features  of  the  proposed  standard,  ffowever, 
they  are  abstracted  from  the  standard  and  presented  generically.     (Standard-specifc  mat- 
ters are  discussed  in  Section  4 . )  They  are  all  based  on  personal  and  organizational 
experience  and  on  the  FADPUG/QA  report. 

3.1  Separate,  at  least  conceptually,  the  information  content  requirements  from  the 
information  display  (actual  document)  requirements.    The  required  information  items  can 
be  regarded  as  elements  of  a  database,  the  "Ccmprehensive  Information  Base"  (CIB)  . 
Information  should  be  created,  captured  and  collected  separately  from  its  display.  All 
docunents  produced  according  to  the  standard  are  printouts  of  part  or  all  of  the  CIB. 

Reasons : 

(a)  Eltijiiasizes  ccmpatibility  with  a  wide  variety  of  syston  development  metho- 
dologies and  life-cycle  models.    The  order  in  which  the  elonents  of  the  CIB  are  updated 
is  determined  by  the  methodology  and  life-cycle  model  used,  not  by  their  arranganent  in 
the  resulting  documents. 

(b)  Simplifies  the  documentation  effort.    The  act  of  updating  a  database  is 
more  palatible  to  many  programmers  than  is  the  act  of  producing  an  entire  docunent. 

(c)  Facilitates  documentation  in  step  with  the  development  effort,  since  only 
a  few  itans  need  to  be  entered  into  the  CIB  at  any  one  time  as  development  progresses. 

(d)  Facilitates  flexibility.    It  should  be  recognized  that  documentation 
standards  prescribe  reference  documents.    Other  types  of  documents  may  be  needed  with 
arrangements  of  information  different  fron  that  prescribed.    The  concept  of  the  CIB 
permits  easy  correlation  between  non-standard  documents  and  the  information  require- 
ments prescribed  by  the  standard. 

3.2  Recognize  that  all  documents  produced  according  to  the  standard  have  similar  infor- 
mational and  organizational  requirements;  they  differ  primarily  in  degree  of  detail. 

3.3  Organize  information  in  all  docunents  along  a  system  decomposition  (compDnent) 
orientation.    Inputs,  outputs,  dialogues,  staff  actions,  and  other  items  should  be 
clearly  aligned  with  the  components  to  which  they  pertain. 

Reasons : 

(a)    System  decomposition  along  component  lines  such  as  functions,  actions, 
events,  or  sub-systems  is  characteristic  of  modem  methods  of  systom  development.  This 
is  true  v*\ether  analysis  is  done  along  functional  or  data-driven  lines. 
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(b)  An  action  or  event  orientation  facilitates  the  understanding  (for  design, 
use,  and  operation) 

of  interactive  systems. 

(c)  The  segregation  of  inputs  and  outputs  fran  components  or  functions  in  the 
FIPS  38  docunents  make  preparation  and  use  of  the  documents  and  implanentation  of  sys- 
tems from  them  very  difficult  ( for  all  but  the  rarely  occurring  single  function  sys- 
tems) .    The  FIPS  38  organization  reflects  a  hard\Aare  orientation  which  is  rarely  of  pri- 
mary concern  to  the  elucidation  of  the  system  being  docunented  and  implanented. 
Hardware  should  form  the  basis  of  docunent  organization  only  v*ien  it  forms  the  basis  of 
the  components. 

(d)  Facilitates  systems  analysis.    If  documentation  is  done  in  step  with  the 
developement  effort,  the  need  for  further  analysis  and  the  types  of  questions  that 
should  be  asked  are  made  very  clear  through  this  organization. 

3.4  Broaden  the  scope  of  the  input  and  output  requirements  of  FIPS  38  to  include  com- 
mand, edit  and  other  languages  to  be  developed  by  the  implementers;  dialogue  and  tran- 
sactions; function  keys  and  special  hardware;  interactive  graphics;  and  text  processing. 

Input  and  output  are  too  cut  and  dried  for  the  interactive  and  real-time  worlds;  the 
other  categories  are  quite  necessary  to  facilitate  and  simplify  the  documentation 
effort,  and  increase  understandability. 

3.5  Encourage  graphics  in  documents  such  as  function  charts,  data  flow  diagrams,  Gantt 
and  pert  cliarts,  Petri  net  diagrams,  decision  tables,  finite  state  transition  diagrams, 
and  system  and  logic  flow  charts . 

3.6  Provide  for  validity  of  the  document.  Each  document  should  have  provision  for  dis- 
cussion of  its  testing  against  the  actual  system  being  developed  or  in  operation. 

3.7  Provide  for  discussion  of  management  considerations,  or  reference  to  program 
development  and  configuration  managanent  plans. 

3.8  Provide  linkage  to  Test  Plans  and  Results  of  Tests.    Such  references  should  appear 
in  all  functional  areas  and  anyvA^ere  else  v*here  the  validation  of  the  system  is  criti- 
cal - 

4.     SYNOPSIS  OF  PROPOSED  STANDARD 

4.1  The  individual  items  of  required  information  (the  data  elonents  of  the  CIB)  are 
called  "docimentation  topics,"  and  each  begins  with  a  prescribed  paragraph  nuriber  and 
title. 

4.2  The  docunentation  topics  fall  into  four  broad  categories  called  "sections."  Section 
1  deals  with  general  information,  section  2  deals  with  management  matters,  and  sections 
3  and  4  describe  the  system  requirements.    It  is  frequently  convienent  to  regard  a  sys- 
tem as  made  up  of  components  (also  called  functions,  subsystems,  actions,  events,  etc.). 
Section  3  is  used  to  provide  an  overview  of  the  system  and  an  enumeration  of  its  com- 
ponents.   Each  ccmponent  is  described  in  detail  in  section  4.     Section  3  may  also  be 
used  to  provide  information  common  to  many  components.    If  there  is  an  active  database 
administration  role  associated  with  the  system  being  doconented,  then  it  is  suggested 
that  the  data  items  be  discussed  in  detail  in  section  3,  and  enumerated  v^ere  appropri- 
ate in  section  4.    The  goal  of  maximim  understandability  should  determine  v^here  informa- 
tion is  placed,  if  the  standard  permits  a  choice  of  section  or  documentation  topic.  If 
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the  canponent  approach  is  not  used  then  section  4  my  be  anitted. 

4.3  Paragraph  nimbers  are  of  the  form 

<  section  or  sub- section  n\jnber>  :<  topic  nijnber> 
(jcrnponents,  sub-sections,  and  topics  are  all  nanbered  in  the  manner  in  which  paragraphs 
are  nanbered  in  FIPS  38.     (E.g.  "3.4.5")    Top-level  conponents  have  level-one  paragraphs 
(i.e.  just  positive  integers).    Sub-ccmponents  have  level-two  paragraphs,  etc.  For 
exanple,  if  ccmponent  3  has  2  subcanponents ,  they  WDuld  be  nai±)ered  3.1  and  3.2.  (Zero 
is  also  acceptable  as  a  top^- level  ccmponent  nariber.) 

4.4  Sections  1,  2,  and  3  have  no  subsections.  Section  4  has  a  subsection  for  each  ccm- 
ponent enimerated  in  section  3.    Section  4  subsections  are  nanbered  thus: 

4. < ccmponent  nariber > 

4.5  The  types  of  information  to  be  provided  for  the  system  as  a  v>hole  and  for  each  of 
its  conponents  are  the  same.    Hence  the  topic  nariber s  for  section  3  and  each  sub- 
conponent  of  section  4  are  identical . 

4.6  The  table  below  enanerates  the  docanentation  topics  in  the  order  in  v^ich  they  are 
to  appear  in  all  documents  prescribed  by  the  standard.     (They  appear  in  order  of 
increasing  paragraph  nariber.)    Shown  are  the  paragraph  naribers  and  titles  and  recommen- 
ded applicability.    As  a  miniman  it  is  recommended  that  topics  denoted  by  an  "m"  be 
applicable;  however,  it  is  highly  reconmended  that  topics  denoted  by  an  "x"  eilso  be 
applicable.    For  each  docanentation  topic,  the  standard  provides  guidance  on  vhat  infor- 
mation should  be  provided  for  each  document  (such  as  the  FD,  SS,  etc.)  .    Hovever,  such 
guidance  is  for  the  conpleted  finalized  docanents;  the  standard  encourages  production  of 
docanaitation  in  step  with  development.    This  may  result  in  production  of  incomplete 
versions  of  the  docanents.    The  docanents  would  be  finalized  at  the  end  of  the  develqp- 
moit  effort. 
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Docunentation  Topics  and  Their  Applicability 
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RECORDER'S  COMMENTS 


3.    A  Proposed  Documentation  Standard  Based  on  a  System  Decomposition  and  Information  Base; 
Approach,  Saul  A.  Zaveler. 

3.1  Summary  of  Discussions 

There  is  an  analogy  between  documentation  and  software.  We  can  learn  how  to  structure 
documentation  from  how  we  structure  software. 

The  Parnas  method  of  applying  software  structuring  principles  to  documentation  was 
discussed.    Parnas  supports  two  principles  in  particular: 

•  Information  hiding  --  if  it's  likely  to  change  or  if  no  one  else  needs  to  know  about 
it,  hide  it  away. 

•  Separation  of  concerns  --  if  items  are  not  similar,  don't  put  them  together. 

Parnas'  software  requirements  and  design  documents  were  listed.  The  discussant  then  asked 
the  speaker  whether  the  Parnas  approach  fit  in  with  the  speaker's  approach.  The  speaker 
replied  that  the  type  of  standard  he  is  proposing  is  compatible  with  Parnas  as  well  as  with 
the  many  others  he  had  enumerated.  The  information  is  similar,  but  it  is  organized 
differently  with  different  terminology. 

The  second  discussant  commented  that  we  have  heard  some  very  specific  considerations 
relating  to  the  need  to  revise  FIPS  Pub.  38.  It  seems  that,  implicit  in  the  method  of 
divorcing  the  display  requirements  from  the  information  collecting  requirements,  is  the 
answer  to  an  earlier  question  on  getting  usable  documentation.  Documentation  will  be  more 
palatable  if  the  producers  can  update  as  they  go  along,  without  worrying  about  how  it  will 
appear  later  in  the  display. 

It  may  be  difficult,  while  defining  the  requirement,  to  also  define  the  functions.  In  fact, 
functional  requirements  breakdowns  may  not  be  appropriate,  especially  for  higher  levels  of 
documentation.  The  current  standard  doesn't  tell  what  to  document  first,  only  what  is  left 
out. 

3.2  Summary  of  Questions 

•  Q:  There  are  many  overlapping,  even  contradictory  standards,  within  the  Government. 

Can  these  be  coordinated? 

A:  One  way  to  resolve  the  severity  of  major  conflicts  is  to  define  requirements  to 
be  met  by  the  standard  until  they  become  very  clear,  then  the  solution  becomes 
apparent.  To  solve  the  problem  of  coordination,  develop  a  reference  model  first, 
then  develop  the  standards  in  subparts  that  will  fit  in  the  total  picture. 

t    Q:  What  about  standards  for  large,  decentralized  systems? 

A:  The  guidelines  and  standards  for  small  systems  are  a  subset  of  the  large.  If  you 
create  a  set  of  standards  that  encompasses  the  larger  system,  the  smaller  system 
will  have  less  complex  requirements.  Develop  subset  standards  of  big  systems  so 
they  represent  the  small  and  medium,  then  develop  samples  for  each  (small,  medium 
and  large)  to  use  as  teaching  tools. 

•  Q:  Does  it  pay  to  document  a  small  system? 

A:  Most  organizations  have  a  threshhold  of  time  and  money  below  which  documentation 
is  not  required.  This  is  based  on  the  assumption  that  the  software  can  be 
rewritten  with  less  cost.  However,  lack  of  documentation  makes  data  unacces- 
sible,  and  this  approach  may  be  a  self-fulfilling  prophecy:  if  you  don't 
document,  you  will  have  to  do  it  over  the  next  time. 
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MODERATOR'S  COMMENTS 


Based  on  the  papers  presented,  questions  raised,  answers  and  discussions,  the  following 
conclusions/recommendations  were  reached  during  this  session: 

1.  Why  do  we  need  documentation? 

To  know  what  the  documented  product  does,  how,  and  for  whom.  Without  this  informa- 
tion, the  product  (software,  procedures,  system,  etc.)  may  be  lost.  The  level  of 
documentation  must  be  cost  effective.  The  user  of  the  product  must  be  able  to 
understand  and  use  the  product  easily.  If  there  is  management  involved  (usually, 
except  for  user-owned  microcomputers),  the  documentation  must  allow  management 
information  for  planning,  accounting,  control,  etc. 

2.  What  should  be  the  process  of  developing  better  documentation  standards? 

To  develop  such  standards,  the  systems  (project)  approach  should  be  used  throughout 
the  process.  Emphasis  should  be  placed  on  coordination,  overall  applicability,  and 
consensus . 

3.  What  should  be  the  characteristics  of  better  documentation  standards?    (See  the  first 
paper  for  more  details.) 

Documentation  standards  must  be  stated  in  a  conceptual  project  context;  they  must  be 
adaptable  to  each  project/system's  situation;  they  must  be  complete  and  thorough  with 
ample  definitions  and  guidance  for  the  authors;  they  must  be  manageable  and  based  on 
what  is  known  to  work.  They  must  also  assist  the  authors  in  providing  documentation 
that  is  organized,  logical,  objective,  tailored  to  the  reader/user,  clear,  concise, 
and  that  contains  all  of  the  information  needed  and  nothing  else. 

4.  How  should  documentation  standards  assist  in  the  production  of  documentation? 

They  should  provide  guidance  for  context,  concepts,  terms,  content,  and  format.  They 
also  should  encourage  the  use  of  state-of-the-art  approaches  and  tools  available  for 
documentation.    (See  Session  C  for  more  details.) 

5.  Who  should  produce  documentation? 

The  standards  should  be  written  for  technical  writers,  who  should  produce  the  final 
documentation  and  who  may  or  may  not  have  any  experience  in  computers,  programming, 
systems  development,  implementation  and  operation. 


173 


NBS  FIPS  Software  Documentation  Workshop,    March  3,  1982 


Microcomputer  Systems  Users  Need  Better  Documentation 


Richard  A.  Bassler,  PhD,  CDP,  CDE 


Professor  of  Computer  Systems  Applications 
Center  for  Technology  and  Administration 
College  of  Public  Affairs 
The  American  University 
Washington,  DC  20016 


From  the  initial  pioneering  days  of  microcomputers,  documentation  has  been  the 
weak  link  between  use  of  the  machines  and  the  vast  number  of  potential  users.  Many  of 
the  microcomputer  hardware  and  software  suppliers  of  the  early  days  are  now 
sufficiently  large  and  financially  healthy  enough  to  be  able  to  spend  resources  toward 
communication  with  users.  The  success  of  the  microcomputer  has  attracted  large 
computer  manufacturers  to  the  marketplace.  Large  manufacturers  such  as  IBM  and  Xerox 
are  likely  to  make  sure  that  the  user  will  have  documentation  that  is  usable.  With  the 
proliferation  of  microcomputers,  user's  groups  have  created  a  form  of  documentation 
that  is  verbal.  This  mutual  aid  made  microcomputing  survive,  if  not  flourish,  during  its 
infancy  days  of  less  than  adequate  documentation.  Third  parties  such  as  publishers  have 
moved  in  to  fill  the  void  in  documentation.  Rapid  expansion  and  survival  within  the 
micro  industry  may  well  depend  on  the  quality  of  the  documentation  furnished. 

Keywords:  beginning  computer  users;  documentation;  hardware  systems  documentation; 
large  computer  manufacturers;  microcomputers;  periodical  literature  and  documentation; 
software  documentation;  user's  groups;  verbal  documentation. 


1.  INTRODUCTION 


Microcomputers  have  a  unique  place  in  the  hierarchy  of  computing.  Arriving  on  the  scene  only 
recently,  they  have  opened  up  a  totally  new  marketplace  for  the  industry.  Along  with  this  new 
marketplace  comes  a  new  class  of  computer  users.  These  new  users  are  not  sophisticated 
computerists.  It  is  more  likely  that  they  do  not  ever  want  to  become  really  knowledgeable  about 
computers  and  computing.  They  want  to  use  the  cheap  computer  power  of  this  technology  for  their 
applications  instead  of  learning  the  technology. 

l.I  The  Early  Days 

The  first  microcomputers  were  typically  in  kit  form.  Most  popular  of  these  were  the  Altair 
series  of  computers,  a  combination  which  really  was  the  prime  mover  in  getting  microcomputers 
into  the  hands  of  hobbyists.  Potential  users  would  buy  a  collection  of  parts,  usually  unidentified  in 
plastic  bags,  and  a  few  sheets  of  documentation  as  assembly  instructions.  Early  pioneers  were  a 
brave  lot,  and  most  of  them  were  ham  radio  operators  or  other  folk  who  had  some  experience  with 
either  hardware  or  software.  The  next  stage  in  this  evolution  was  the  arrival  of  more  sophisticated 
kits  with  some  software,  such  as  the  Processor  Technology  series  of  SOL  computers  and  the  IMSAI. 
These  microcomputer  systems  eventually  were  delivered  in  assembled  form.  As  a  result,  the  number 
of  nontechnically  oriented  users  began  to  increase  rapidly. 
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Documentation  for  these  systems  began  to  show  improvement.  The  manual  for  the  SOL  20  (1) 
was  an  example  of  attempts  to  produce  adequate  documentation.  Although  it  was  still  oriented 
toward  the  kit  builder,  it  did  have  sufficient  information  in  it  to  make  it  tolerably  useful  to  the 
sophisticated  user.  The  manual  was  not  indexed,  and  the  user  v/as  at  the  mercy  of  using  a 
sequential  search  to  find  any  particular  item. 

1.2  Current  Systems 

Recent  microcomputers,  such  as  the  OSBORNE  1,  have  user's  manuals  directed  toward  the 
user  with  little  experience.  For  example,  the  OSBORNE  1  User's  Reference  Guide  (2)  states  in  its 
introduction  that: 

The  OSBORNE  1  has  been  designed  to  make  you  more  productive  in  your  professional 
life.  If  you  are  a  typical  OSBORNE  1  owner,  you  will  probably  never  write  a  computer 
program;  you  do  not  have  to  in  order  to  use  this  computer.  In  fact,  you  can  discard  the 
traditional  concept  of  computers.  Your  OSBORNE  1  will  perform  a  multitude  of  tasks 
for  you.  You  simply  instruct  the  computer  by  having  it  play  a  program  on  a  diskette, 
much  as  you  would  instruct  your  stereo  system  by  playing  a  record  or  cassette  tape.  In 
fact,  learning  to  use  your  OSBORNE  1  computer  is  no  more  complex  than  learning  to 
use  a  stereo  system. 

This  is  an  indicator  of  the  marketplace  that  the  current  crop  of  microcomputer  manufacturers 
is  aiming  at.  IBM,  Xerox,  V/ang,  and  most  other  large  vendors  have  also  fielded  small  computers 
aimed  at  this  burgeoning  new  arena  for  the  sale  of  large  volumes  of  computer  -systems.  It  turns 
out  that  the  process  of  using  any  computer  is  a  little  more  complex  than  Osborne  suggests.  If  the 
whole  movement  toward  mass  use  of  microcomputers  is  to  be  truly  successful,  a  great  deal  of 
attention  needs  to  be  paid  to  the  documentation  of  both  hardware  and  software. 


2.  HARDWARE  SYSTEMS  DOCUMENTATION 


2.1  Trend  toward  Improvement 

Many  of  the  hardware  manufacturers  who  cater  to  the  microcomputer  market  have  been 
paying  attention  to  the  needs  of  their  potential  customers.  Well,  almost.  There  is  still  a  long  way 
to  go  before  the  documentation  for  hardware  will  be  really  useful  to  the  users  who  do  not  want  to 
be  technicians. 

One  example  of  such  improvement  is  in  the  documentation  for  the  Diablo  1650  word  processor 
printer.  This  paper  was  printed  on  such  a  printer/terminal  driven  by  a  state-of-the-art 
microcomputer.  The  author  has  struggled  with  these  two  manuals  for  over  a  year.  The 
documentation  for  this  printer,  available  in  1979,  is  in  two  books.  The  first  of  these,  the  Product 
Description  (3),  and  the  other,  the  Maintenance  Manual  (k),  were  written  for  the  technically 
oriented  person.  The  casual  user  could  not  fathom  what  was  included  and  could  not  begin  to  use 
the  devices  from  these  manuals.  They  are  useful  to  technicians,  but  only  to  those  familiar  with  the 
manuals.  The  lack  of  an  index  inhibits  really  good  usage. 

Later  Diablo  machines  were  delivered  with  an  operator's  guide  (5)  that  was  written  for  the 
technically  unsophisticated  user.  It  describes  how  to  use  the  external  features  of  the  machine  in 
terms  that  most  \VP  operators  can  fathom.  Although  this  was  a  step  forward,  the  newer  operator's 
guide  would  be  more  usable  with  an  index.  Of  course,  in  its  25  pages,  one  could  not  find  the 
detail  that  was  in  the  500  pages  of  the  earlier  manuals.  The  complete  manuals  are  still  available 
for  those  who  want  to  get  into  the  details  and  advanced  features  of  the  printers. 

2.2  Hope  for  the  Future 

With  the  arrival  of  the  IBM  Personal  Computer  (6)  and  the  Xerox  820  (7)  computer,  it  is 
hoped  that  the  large  computer  manufacturers  will  apply  their  experience  in  dealing  with  many 
levels  of  consumers  toward  developing  documentation  to  make  their  small  computer  systems  usable 
by  a  wide  variety  of  users.  Failure  to  do  so  will  result  in  slowing  the  forward  movement  toward 
the  exploitation  of  this  potentially  huge  marketplace. 
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The  idea  that  these  computers  will  be  sold  through  unusual  (for  computers)  marketing 
schemes,  such  as  IBM  in  Sears  Roebuck  stores,  means  that  the  instructions  for  use  must  be  clear 
and  understandable.  For  those  machines  sold  through  computer  stores  such  as  Computerland,  more 
help  would  be  available  from  the  store  staff  to  aid  the  buyer. 


3.  SOFTWARE  SYSTEMS  DOCUMENTATION 


3.1  The  Early  Days 

An  early  effort  in  large-volume  software  documentation  consisted  of  six  manuals  that 
described  the  features  of  the  CP/M  operating  system.  CP/M  is  today  the  preeminent  microcomputer 
operating  system  with  almost  all  microcomputer  manufacturers  offering  it  as  their  standard 
operating  system  or  as  an  option.  Where  CP/M  is  not  furnished  by  the  vendor,  it  is  sometimes 
available  from  a  third  party  software  supplier.  The  original  six  manuals  (8)  could  be  kindly 
described  as  virtually  unreadable  by  the  less  experienced.  Jargon  of  the  microcomputerists 
abounded.  Terms  were  undefined  in  the  document  or  for  that  matter  anywhere  else.  The  final  blow 
was  that  no  index  to  these  documents  was  furnished. 

When  a  user  has  considerable  help  from  other  users,  it  is  possible  to  understand  what  the 
manuals  are  describing.  This  form  of  tutorial  by  other  microcomputer  enthusiasts  was  the  true  form 
of  documentation  of  the  early  systems.  This  method  of  communication  often  exists  today.  There  is 
really  no  substitute  for  the  "hand  holding"  method  of  learning  to  use  a  microcomputer  system. 

3.2  MutUcd  Aid  and  Verbcil  Documentation 

The  microcomputer  user's  group  has  emerged  as  a  viable  way  for  an  individual  to  understand 
the  use  and  peculiarities  of  any  system.  In  fact,  it  might  be  viewed  as  a  forum  of  verbal 
documentation.  Experience  is  passed  on  to  the  newcomers  entering  a  group  of  microcomputer  users. 
Every  city  has  such  groups.  They  are  usually  formed  around  a  background  of  some  common 
denominator.  In  the  Greater  Washington,  DC  area,  there  are  user's  groups  built  around  the  CP/M 
operating  system  and  the  Apple,  Radio  Shack  TRS80,  and  Osborne  microcomputers.  Nationally,  the 
CP/M  User's  Group  distributes  a  wide  variety  of  public  domain  software  in  magnetic  form.  Many  of 
the  local  user's  groups  perform  a  secondary  distribution  service  by  making  several  thousands  of 
programs  available. 

Help  in  using  these  software  packages  is  needed.  The  documentation,  if  any  exists,  is  usually 
poor.  By  seeking  help  from  others  who  have  implemented  such  packages,  one  may  be  able  to  make 
use  of  the  programs.  Also,  there  is  a  learning  experience  connected  with  this  sharing  that  is 
invaluable. 

3.3  Software  Vendors'  Attention  to  Documentation 

In  recent  years,  there  has  been  a  noticeable  improvement  in  the  documentation  of  application 
software  for  micros.  Some  of  the  larger  vendors  have  attempted  to  produce  manuals  and  user's 
guides  that  are  readable  and  understandable  by  a  typical  user.  For  example,  a  reference  manual  for 
the  Radio  Shack  TRSDOS  (Disk  operating  system)  (9)  is  rather  good.  It  is  a  carefully  typeset, 
printed  manual,  with  attractive  illustrations  and  enough  white  space  to  make  it  readable.  The 
manual  begins  with  an  elementary  overview  of  the  hardware  connected  with  this  particular 
operating  system.  Each  feature  of  the  OS  is  explained  in  careful  detail,  and  it  would  be  expected 
that  most  users  would  understand  what  is  being  explained.  There  is  even  a  three-page  index  to  the 
manual.  This  will  help  in  finding  reference  items.  Documentation  for  other  systems  such  as  the 
Apple  and  the  Heathkit  computers  has  improved. 

3A  Publishers'  Attempt  to  Fill  Void 

With  all  the  problems  about  the  CP/M  operating  system  documentation,  it  is  surprising  how 
long  it  took  for  the  publishing  industry  to  come  to  the  rescue.  At  this  writing  there  are  at  least 
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four  1981  books  explaining  how  to  get  the  most  out  of  the  CP/M  operating  system.  Typical  of 
these,  and  probably  the  easiest  to  use  and  most  comprehensive,  is  Thom  Hogan's  book  (10)  on  how 
to  use  CP/M.  This  is  clearly  written  and  has  an  elementary  introduction  for  the  beginner.  It 
explains  much  of  what  is  covered  in  the  original  CP/M  manuals.  Even  experienced  users  are 
learning  from  this  book  and  reaching  an  understanding  of  what  they  have  been  doing. 

Besides  covering  operating  systems,  publishers  are  helping  to  fill  the  void  in  documentation 
for  several  computer  languages.  Several  books  about  Microsoft  BASIC  are  available.  CBASIC2  is  the 
subject  of  a  volume  (11)  devoted  to  more  extensive  examples  about  the  syntax  and  use  of  the 
language  than  were  furnished  by  the  vendor. 


It.    SOFTWARE  FROM  THE  PUBLIC  DOMAIN  AND  THE  PERIODICAL  LITERATURE 


'^.l  User's  Group  Software  Documentation 

When  software  is  passed  on  through  informal  user  groups,  typically  the  documentation  is 
passed  on  in  a  simple  manner.  It  will  probably  consist  of  user  instructions  on  how  to  run  the 
program.  If  there  is  some  user  interaction  to  the  program,  it  may  be  possible  to  run  the  program 
without  help.  Frequently,  the  source  code,  if  furnished,  will  contain  enough  remarks  to  make  it 
possible  to  fathom.  This  is  fine  for  the  experienced  user,  but  the  beginner  is  usually  lost  without 
some  help  from  more  detailed  user  documentation. 

All  software  that  is  shared  by  user's  groups  is  really  not  in  the  public  domain.  Much  of  it  is 
pirated  commercial  software.  The  documentation  for  these  programs  frequently  is  a  multi- generation 
xerographic  copy  that  may  or  may  not  be  readable.  Part  of  the  blame  for  the  extensive  piracy  of 
software,  passing  in  the  name  of  "sharing,"  is  caused  by  the  inability  of  the  potential  users  to 
really  know  whether  a  program  will  run  on  their  system  and  whether  it  will  do  the  tasks  expected 
of  it.  Some  users  of  this  class  of  software  rationalize  their  pirating  with  the  explanation  that  they 
are  "testing  for  evaluation"  in  their  user  environment.  Some  intend  to,  and  do,  buy  legitimate 
copies  when  proven  useful  in  their  own  system  and  application. 

'^.2  Programs  in  the  Periodical  Literature 

All  the  journals  that  have  sprung  up  in  the  microcomputer  area  in  the  past  few  years  are 
publishing  programs  of  virtually  any  type.  Some  are  well  documented,  others  are  not.  Editorially, 
these  journals  have  a  long  way  to  go  to  achieve  the  quality  desired.  Frequently  programs  are 
published  that  simply  will  not  run  as  listed  in  the  journal.  Later  editions  of  that  journal  will  have 
corrections  listed  in  the  letters  to  the  editor.  Of  course,  one  can  write  off  to  an  educational  foray 
the  experience  in  trying  to  get  some  of  this  software  to  work. 

Some  of  the  code  written  for  these  journals  is  written  in  the  style  of  a  few  years  ago,  when 
micro  memory  was  expensive.  Today,  when  64K  memories  are  the  norm  for  serious  users,  BASIC 
programs  written  in  a  style  to  save  on  memory  usage  are  unacceptable.  Writing  clearly  documented 
programs  that  are  readable  to  the  user  is  more  important  than  trying  to  save  bytes  in  internal 
memory  usage.  Progress  is  being  made  along  these  lines. 


5.    DOCUMENTATION  STANDARDS  FOR  MICROCOMPUTER  SYSTEMS 


5.1  Consumerism  in  the  Software  Marketplace 

The  best  way  to  get  better  documentation  for  microcomputers  is  through  consumer  action. 
When  potential  buyers  have  good  evaluations  of  available  software  io  pass  judgment  on  the  quality 
of  the  vendor-supplied  documentation,  then  resistance  in  the  marketplace  would  take  care  of  the 
poor  cases.  The  periodicals  are  beginning  to  pay  attention  to  the  quality  of  vendor  documentation 
in  their  reviews  of  both  hardware  and  software.  InfoWorld  regularly  reviews  both  hardware  and 
software   that   is   available  in   the   marketplace.   Documentation   is  one  of   the  five  criteria  for 
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evaluating  a  software  package.  The  ratings  assigned  are  poor,  fair,  good,  and  excellent.  A  recent 
review  (12)  involved  a  Hewlett-Packard  hardware  and  software  package  called  Business  Assistant. 
The  documentation  for  this  system  was  rated  excellent.  The  reviewer  comments: 

Hewlett-Packard  has  resisted  the  temptation  to  which  most  CP/M  compatible 
hardware  suppliers  have  succumbed.  The  HP-125  comes  with  a  totally  rewritten  and 
indexed  manual  for  CP/M.  Gone  are  the  traditional  set  of  seven  Digital  Research 
manuals  that  you  must  read  in  parallel  to  comprehend  them.  This  feature  alone  is  nearly 
worth  the  price  differential  between  the  125  and  less  expensive  systems. 

The  reference  manual  is  well  written  and  explains  exactly  how  things  work  in  the 
HP-125  implementation  of  CP/M  rather  than  employing  the  traditional  approach  of 
supplying  a  few  scant  notes  and  the  Digital  Research  CP/M  Alteration  Guide.  (12) 

In  a  buyer's  market,  the  consumer  is  a  powerful  force.  With  the  low  price  of  microcomputer 
systems  and  their  related  software,  the  only  way  to  survival  is  through  volume.  No  longer  can  a 
software  or  hardware  vendor  expect  to  capture  the  development  cost  of  a  software  package  in  the 
first  few  sales.  Competition  is  fierce  in  the  microcomputer  field.  The  user  with  a  CP/M-based 
system  can  select  from  a  dozen  excellent  word  processing  packages.  The  one  that  furnishes  the 
best  documented  user  instructions  and  that  can  accomplish  all  the  tasks  of  the  application  will  win. 
The  user  can  easily  evaluate  the  quality  of  the  documentation.  Manuals  for  virtually  every  micro 
software  package  can  be  purchased  separately  from  the  software  for  evaluation  purposes. 

5.2  Need  for  Experts  in  Communicating 

Computer  documentation  in  general,  and  for  the  microcomputer  in  particular,  is  too  important 
to  be  left  to  the  computer  expert.  What  is  needed  is  a  whole  new  generation  of  experts  on 
communicating  technical  ideas  in  the  language  of  the  user.  We  can  no  longer  expect  that  the  user 
of  com.puters  will  learn  the  language  of  the  technology.  There  are  many  potential  users  who  have 
no  computer  background  and  no  desire  to  attain  this  expertise.  The  documents  furnished  with  micro 
software  will  be  the  determining  factor  in  the  consumer  acceptance  of  any  software  package. 

5.3  Importance  of  Index 

Few,  if  any,  microcomputer  manuals  have  been  indexed  until  recently.  Reviewers  have 
complained  about  the  absence  of  indexes,  or  of  indexes  of  poor  quality.  Virtually  every  book  in  the 
author's  library  is  indexed  except  for  many  of  the  micro  applications  manuals.  The  task  is  not 
difficult  if  done  by  someone  with  experience.  Having  a  workable  index  or  not  in  a  manual  may 
make  the  difference  between  survival  and  disaster  for  a  micro  vendor. 

5A  Testing  the  Documentation 

The  documentation  must  be  tested  in  the  user  arena.  No  longer  will  it  be  acceptable  to  pass 
it  along  in  the  office  to  see  if  all  the  technical  jargon  is  correct.  Tests  must  be  made  with  the 
users  who  will  have  to  cope  with  the  foibles  of  the  documentation.  They  must  be  allowed  to  pass 
along  com.ments  and  suggestions  that  must  be  listened  to  and  incorporated  in  the  documentation 
before  the  final  versions  are  published.  Frequent  revisions  must  be  made  to  correct  the  problems 
discovered  though  use.  The  cost  of  this  must  be  part  of  doing  business  in  this  high-volume  arena. 


CONCLUSION 


Early  microcomputer  systems  were  notable  for  the  poor  quality  and  quantity  of  their 
documentation.  The  industry  has  recently  begun  to  recognize  the  need  for  quality  documentation 
oriented  toward  the  mass  market  of  microcomputer  buyers.  Possibly  the  survival  of  the 
microcomputer  industry,  and  certainly  its  growth,  will  be  affected  by  the  recognition  of  this  need. 
Quality  documentation  can  come  only  from  putting  communication  experts  on  the  task.  Hardware 
and  software  advances  were  brought  about  by  putting  design  and  engineering  experts  to  work  on  the 
task.  The  future  looks  bright  and  exciting. 


178 


7.  REFERENCES 


1.  Sol  Systems  Manual,  6200  Hollis  Street,  Emeryville,  CA  9^^608,  Processor  Technology 
Corporation,  1976,  700+  pages  (pages  numbered  within  chapters),  not  indexed. 

2.  OSBORNE  1  User's  Reference  Guide,  26500  Corporate  Avenue,  Hayward,  CA  945^15, 
Osborne  Computer  Corporation,  Undated  (presumably  1981),  225+  pages  (pages  numbered  within 
chapters),  not  indexed,  table  of  contents  without  page  numbers. 

3.  Series  1650  Word  Processor  Printers  and  Terminals,  Product  Description,  Preliminary, 
Document  Number  90^^02-00,  3190  Corporate  Place,  Hayward,  CA  9'f5't5,  Diablo  Systems,  Inc., 
March  1979,  200+  pages  (pages  numbered  within  chapters),  not  indexed. 

if.  Series  1640/1630  Printers  and  Terminals,  Maintenance  Mcinual,  Preliminary,  Document 
Number  90^^13-00,  3190  Corporate  Place,  Hayward,  CA  9't5't5,  Diablo  Systems,  Inc.,  3uly  1979, 
300+  pages  (pages  numbered  within  chapters),  not  indexed. 

5.  Series  1650  Word  Processor  Terminal  Operators  Guide,  Document  Number  90'f05-02,  2'f500 
Industrial  Boulevard,  Hayward,  CA  9't5'f5,  Diablo  Systems  Incorporated,  July  1980,  25  pages, 
not  indexed. 

6.  Lemmons,  Phil.  "The  IBM  Personal  Computer:  First  Impressions,"  BYTE,  Volume  6,  Number 
10,  pp.  26,  28,  30,  32,  3^^,  October  1981. 

7.  Maggie  Cannon.  "Major  Manufacturers  Eye  World  Market  for  Small  Computers," 
InfoWorld,  Volume  3,  Number  20,  p.  51,  October  5,  1981. 

8.  Digital  Research  CP/M  Documentation  Version  lA  (six  volumes): 

I.  An  Introduction  to  CP/M  Features  and  Facilities,  35  pages; 

II.  CP/M  Assembler  (ASM)  User's  Guide,  22  pages; 

III.  CP/M  Dynamic  Debugging  Tool  (DDT):  User's  Guide,  19  pages; 

IV.  CP/M  System  Alteration  Guide,  23  pages  +  appendices; 

V.  CP/M  Interface  Guide,  38  pages; 

VI.  ED:  A  Context  Editor  for  the  CP/M  Disk  System:  User's  Manual,  17  pages. 

Box  579,  Pacific  Grove,  CA  93950,  Digital  Research,  1976,  not  indexed. 

9.  TRSDOS  &  Disk  Basic  Reference  Manual,  One  Tandy  Center,  Fort  Worth,  TX  76102,  Radio 
Shack,  a  division  of  the  Tandy  Corporation,  1979,  200+  pages  (pages  numbered  within 
chapters),  indexed. 

10.  Hogan,  Thom.  Osborne  CP/M  User  Guide,  630  Bancroft  Way,  Berkeley,  CA  9^^710, 
OSBORNE/McGraw-Hill,  1981,  283  pages,  indexed. 

11.  Osborne,  Adam,  Gordon  Eubanks  3r.,  and  Martin  McNuff.  CBASIC  User  Guide,  630 
Bancroft  Way,  Berkeley,  CA  9'f710,  OSBORNE/McGraw-Hill,  1981,  215  pages,  indexed. 

12.  Milewski,  Richard  A.  "The  HP- 125  Business  Assistant  from  Hewlett-Packard,"  InfoWorld, 
Volume  3,  Number  20,  pp.  37-39,  October  5 

1981. 


179 


RECORDER'S  COMMENTS 

2.    Microcomputer  Systems  Users  Need  Better  Documentation,  Richard  A.  Bassler 

2.1  Summary  of  Discussions 

The  problems  of  documentation  for  microcomputers  are  an  illustration  of  "we  learn  from  our 
mistakes  --  we  have  learned  how  to  do  these  mistakes  well."  If  we  knew  how  to  produce  good 
manuals  for  minicomputers  and  mainframes,  we  would  know  how  to  produce  good  ones  for  micros. 
Since  micros  are  bought  by  the  user,  the  microcomputer  market  may  assume  a  leading  role  in 
forcing  us  to  do  a  better  job  of  documentation. 

A  tongue-in-cheek  comment  was  made  that  the  manuals  are  the  real  thing.  The  hardware  is 
merely  an  attempt  to  meet  the  manuals.  A  number  of  extensive  disclaimers  were  read  to 
support  this  view. 

2.2  Summary  of  Questions 

•  Q:  How  can  we  incorporate  standards  for  micros  into  the  classic  type  of  develop- 

mental systems?    Are  they  two  separate  problems? 

A:  Yes.    This  documentation  is  for  naive  users. 

•  Q:  Do  you  have  any  proposed  standards  for  documentation  of  microcomputer  applica- 

tion programs  and  systems? 

A:  Documentation  must  be  approached  each  time  on  a  unique  basis.     It  must  be 
comprehensible  and  understandable  to  the  naive  user. 


180 


Session  F:    Enhancing  Software  Sharing 


INTRODUCTION 

Lenore  S.  Maruyama,  Moderator 

Network  Development  Office,  Library  of  Congress 
Washington,  D.C. 

This  session  considers  different  aspects  of  software  sharing  which,  in  a  broad 
context,  encompasses  the  use  of  software  created  by  persons  or  organizations  outside 
one's  inmediate  institutional  affiliations.  Because  of  the  increasing  importance  of 
software  sharing  in  all  sectors  (public/private,  for-prof it/not-for-profit)  ,  standards 
and  standardized  techniques  have  been  or  are  being  developed  to  facilitate  the  sharing 
process. 

In  a  recent  report.  An  Assessment  and  Forecast  of  ADP  in  the  Federal  Government 
(published  by  the  National  Bureau  of  Standards  based  on  research  conducted  by 
International  Data  Corporation) ,  it  was  estimated  that  the  Federal  government  spent  about 
$559  million  on  software  in  1979.   (1)     These  expenditures  were  categorized  as  follows: 

$117  million  (21%)  Systems  Software 

66  million  (12%)  Utility  Software 

376  million  (66%)  Applications 

Of  the  $117  million  spent  for  systems  software,  about  53%  ($62  million)  had  been  spent  on 
internally  developed  software;  of  the  $66  million  for  utility  software,  50%  ($33  million) 
had  been  spent  on  internally  developed  software;  and  of  the  $376  million  for  appli- 
cations, 83%  ($312  million)  had  been  spent  on  internally  developed  software.  These 
figures  are  important  not  only  in  terms  of  the  standards  and  standardized  techniques 
being  discussed  in  this  session  but  also  for  the  entire  software  sharing  process  which 
has  the  potential  of  saving  the  Federal  government  (and  others)  substantial  amounts  of 
money . 

The  first  three  papers  address  various  information-gathering  techniques.  "Effec- 
tive Bibliographic  Standards  for  Computer  Software:  Improved  Documentation  and  the  Need 
for  'Title  Page'  Equivalents"  by  Sue  A.  Dodd  presents  bibliographic  procedures  on  how  to 
identify  and  describe  a  computer  program  and  proposes  the  inclusion  of  a  user  header 
label  to  record  the  necessary  bibliographic  information.  Ms.  Dodd  is  an  associate 
research  librarian  in  the  Social  Science  Data  Library  at  the  University  of  North 
Carolina,  and  following  several  years  of  active  involvement  in  the  area  of  bibliographic 
control  for  machine-readable  data  files,  she  has  compiled  a  cataloging  manual  for 
machine-readable  data  files.  "Standards  for  Bibliographic  Control  of  Machine- Readable 
Data  Files"  by  Lenore  S.  Maruyama  describes  standards  in  the  area  of  automated  biblio- 
graphic control,  including  a  new  format  for  machine-readable  data  files,  and  reviews  the 
elements  in  FIPS  30  for  software  summaries  as  well  as  proposes  a  new  standard  for  numeric 
data  files.  Ms.  Maruyama  is  a  senior  information  systems  specialist  in  the  Network 
Development  Office  of  the  Library  of  Congress,  and  in  addition  to  her  involvement  with 
numerous  automation  projects  at  the  Library,  she  has  compiled  seven  MARC  (machine- 
readable  cataloging)  formats,  the  most  recent  being  the  one  for  machine-readable  data 
files.  In  "The  Computer  Program  Abstract  as  Software  Documentation,"  Margaret  K.  Butler 
discusses  the  development  of  the  recently  completed  American  National  Standard  for  Com- 
puter Program  Abstracts  and  its  role  in  software  sharing.  Mrs.  Butler  is  a  senior 
computer  scientist  at  Argonne  National  Laboratory  and  director  of  the  National  Energy 
Software  Center.  She  has  participated  in  standards  work  as  a  member  of  the  ANSI  X3  SPARC 
(Standards  Planning  and  Requirements  Committee)  and  chaired  Technical  Committee  X3K7  on 
Computer  Program  Abstracts. 
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The  remaining  three  papers  present  techniques  that  are  intended  to  facilitate  the 
sharing  process.  "An  Integrated  Machine-Readable  Data  Documentation  System"  by  Richard 
C.  Roistacher  describes  the  use  of  a  text  formatter  to  manipulate  machine- readable  text, 
including  the  preparation  of  documentation.  Mr.  Roistacher  is  a  research  associate  at 
the  Bureau  of  Social  Science  Research  in  Washington,  D.C.,  and  his  major  research 
interests  are  in  the  areas  of  social  science  computing  and  data  analysis  and  the  social 
and  organizational  effect  of  computer  networks.  (Although  Mr.  Roistacher 's  paper  has 
been  included  in  these  proceedings,  he  was  not  able  to  present  the  paper  at  the  work- 
shop.) In  "Compilation  of  Bibliographic  Data  Element  Dictionaries,"  Madeline  M. 
Henderson  describes  a  project  in  progress  to  standardize  techniques  to  compile  a  data 
element  dictionary  for  all  elements  used  in  processing  Federal  documents.  Mrs. 
Henderson,  now  a  consultant  in  information  management,  analysis,  and  assessment,  had  been 
manager  of  the  ADP  Information  Analysis  Project  in  the  Institute  for  Computer  Sciences 
and  Technology  of  the  National  Bureau  of  Standards  until  her  retirement  in  1979. 
Finally,  "Capital  Games:  the  Problem  of  Compatibility  of  Bibliographic  Citations  in  Data 
Bases  and  in  Printed  Publications"  by  Hans  H.  Wellisch  discusses  the  problems  of  convert- 
ing data  from  bibliographic  files  to  references  or  footnotes  in  monographs  or  journals 
because  of  differing  capitalization  practices  in  the  latter.  Mr.  Wellisch  is  a  professor 
in  the  College  of  Library  and  Information  Services  at  the  University  of  Maryland,  and  his 
major  interests  include  subject  indexing,  the  linguistic  aspects  of  information  science, 
the  physical  planning  of  libraries,  and  the  history  of  library  and  information  work. 
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MBS  FIPS  Software  *Documentati on  Workshop,  March  3,  1982 

Effective  Bibliographic  Standards  for  Computer  Software: 
Improved  Documentation  and  the  Need  for  "Title  Page"  Equivalents 

Sue  A.  Dodd 

Institute  for  Research  in  Social  Science 
University  of  North  Carolina 

Bibliographic  control  over  computerized  information  has  slowly  been 
evolving  within  the  library  and  information  science  profession  during  the 
last  decade.  A  major  landmark  that  helped  to  focus  increased  interest  in 
bibliographic  control  of  computerized  information  was  the  inclusion  of 
Chapter  9  on  machine-readable  data  files  (MRDF)  in  the  second  edition  of 
the  Anglo-American  Cataloguing  Rules  (AACR2).  Publication  of  these  rules  in 
1978,  coupled  with  a  number  of  other  events,  including  the  compilation  of  a 
MARC  (MAchine  Readable  Catalog)  format  for  MRDF  provided  some  important  tools 
for  establishing  bibliographic  control  over  the  proliferation  of  data  files 
and  computer  software.  General  purpose  computer  software  must  be  properly 
identified  with  sufficient  bibliographic  data  elements  to  be  processed  in 
turn  by  librarians  and  information  scientists,  converted  into  catalog 
records  and  data  abstracts,  and  finally  integrated  into  existing  automated 
retrieval  systems.  This  paper  presents  procedures  on  how  to  identify  and 
describe  a  computer  program  and  is  directed  at  those  government  producers 
who  have  the  responsibility  for  providing  descriptive  information  on  available 
Federal  software,  and  for  seeing  that  such  information  reaches  its  intended 
audience. 

Bibliographic  control;  Bibliographic  standards;  Computer  software;  Documentation 
standards;  Machine-Readable  Data  Files  (MRDF) 

1.  INTRODUCTION 

The  Federal  Software  Exchange  Program  was  established  in  1976  by  General  Services  Ad- 
ministration (GSA)  to  promote  Government-wide  sharing  of  common  use  software  owned  by 
Federal  agencies.  In  order  to  provide  for  a  centralized  unit  for  information  on  available 
software,  GSA  established  the  Federal  Software  Exchange  Center  (FSEC)  at  NTIS.  The  vechicle 
for  Federal  software  information  and  dissemination  is  the  Federal  Software  Exchange  Center 
Catalog.  It  contains  software  abstracts  covering  numerous  application  areas  on  programs 
that  are  written  in  a  broad  range  of  computer  languages  for  a  wide  variety  of  hardware.  The 
source  of  information  for  the  abstracts  is  the  Federal  Information  Processing  Standard  Soft- 
ware Summary  (FIPS  Pub.  30).  According  to  Government  regulations  (FPMR  101-36.1068  and  101- 
36.169),  before  a  Federal  agency  can  obtain  a  Delegation  of  Procurement  Authority  (DPA)  to 
acquire  software  from  commercial  sources,  it  must  screen  available  Federal  ADP  resources  by 
reviewing  the  Federal  Software  Exchange  Center  Catalog.  Even  with  these  regulations  and  in- 
formation gathering  procedures,  it  is  commonly  observed  that  available  government-produced 
software  programs  are  seriously  underutilized  both  inside  and  outside  of  government.  This 
condition  is  most  often  attributed  to  the  lack  of  adequate  information  about  and  access  to 
available  software.  Notable  symptoms  of  the  problem  include: 

--  confusion  and  exasperation  in  trying  to  locate  and  acquire 
computer  programs  within  the  Federal  government 

--  insufficient  information  on  the  most  recent  version  or  editions 
of  government-produced  software 

—  published  catalogs  quickly  becoming  out-of-date  with  long  time 
periods  between  updates  or  new  releases  of  catalogs 

--  no  standardization  across  agencies  except  for  the  Federal  Infor- 
mation Processing  Standards  (FIPS)  of  the  National  Bureau  of 
Standards  which  are  often  "observed  only  in  the  breach"  --  in 
addition,  such  forms  are  often  completed  by  persons  not  directly 
involved  with  the  development  of  the  program  being  described 

--  waste  in  government  spending  due  to  a  duplication  of  effort;  new 
software  programs  are  being  budgeted  and  developed  when  similar 
programs  already  exist  within  the  Federal  government 
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While  all  of  these  problems  cannot  be  solved  by  a  singl e  solution,  many  can  be  allev- 
iated by  adhering  to  the  recently  formulated  bibliographic  standards  for  machine-readable 
data  files  (MRDF),  [1]  which  includes  computer  software;  by  integrating  these  standards  into 
existing  documentation;  and  by  converting  this  information  into  a  centralized  automated  on- 
line retrieval  system.    The  process  of  developing  an  efficient  information  retrieval  system 
must  include  the  development  and  enforcement  of  standards  governing  bibliographic  descriptions 
of  computer  programs  and  their  accompanying  documentation.  Bibliographic  control  over  computer- 
ized information  has  slowly  been  evolving  within  the  library  and  information  science  profession 
during  the  last  decade.    A  major  landmark  that  helped  to  focus  increased  interest  in  biblio- 
graphic control  of  computerized  information  was  the  inclusion  of  Chapter  9  on  MRDF  in  the 
second  edition  of  the  Anglo-American  Cataloguing  Rules  (AACR2).  Publication  of  these  rules  in 
1978,  coupled  with  a  number  of  other  events,  including  the  compilation  of  a  MARC  (MAchine 
R^eadable  C^atalog)  format  for  MRDF  provided  some  important  tools  for  establishing  bibliographic 
control  over  the  proliferation  of  data  files  and  computer  software.    Not  unlike  an  author  who 
is  asked  to  follow  standard  descriptive  rules  for  identifying  his  unique  creation,  and  not 
unlike  publishers  who  have  established  among  themselves  standard  publishing  practices  for 
identifying  their  publications,  government  agencies  should  agree  to  follow  accepted  biblio- 
graphic practices  for  describing  and  documenting  computer  software.    General  purpose  computer 
software  must  be  properly  identified  with  sufficient  bibliographic  data  elements  to  be  pro- 
cessed, in  turn,  by  librarians  and  information  scientists,  converted  into  catalog  records 
and  data  abstracts,  and  finally  integrated  into  existing  automated  retrieval  systems.  This 
paper  presents  procedures  on  how  to  identify  and  describe  a  computer  program  and  is  directed 
at  those  government  producers  who  have  the  responsibility  for  providing  descriptive  informa- 
tion on  available  Federal  software,  and  for  seeing  that  such  information  reaches  its  intended 
audience.    The  individual  descriptive  data  elements  required  to  establish  bibliographic  identity 
for  data  files  and  programs  are  outlined.    Immediately  following  are  instructions  on  how  to 
prepare  "title  page"  equivalents  (both  internal  and  external). 

2.  DATA  ELEMENTS  TO  IDENTIFY  SOFTWARE 

Conceptually,  data  elements  for  computer  software  can  be  broken  down  into  at  least  six 
levels:  those  needed  to  identify  a  program  Ce.g.  bibliographic  elements);  those  needed  to 
describe  the  contents  of  a  program  (e.g.  descriptive  summary  or  abstract);  those  needed  to 
classify  a  program  (e.g.  appropriate  classification  codes,  indexing,  or  subject  descriptors); 
those  needed  to  access  or  use  a  program  (e.g.  physical  and  technical  characteristics,  compu- 
ter compatibility,  peripheral  requirements);  those  needed  to  analyze  or  operate  a  program 
(e.g.  citation  of  documentation,  related  publications);  and  those  needed  to  archive  or 
maintain  a  program  (e.g.  agency  records  pertaining  to  the  development,  use,  and  storage  of 
the  program).  Only  the  selected  data  elements  necessary  to  identi fy  a  computer  program  will 
be  discussed  here,  but  the  reader  is  referred  to  other  publications  [2]  dealing  with  other 
descriptive  levels  including  how  to  compile  an  abstract. 

Titl e.  A  formal  computer  software  title  should  be  distinct  from  a  data  set  name  or 
other  computer-related  working  names.  Acronyms  should  be  avoided,  but  if  used,  they  should 
be  explained  in  the  secondary  title  or  subtitle.  For  example: 

TRMETS:  Trace  Metals  Analyses 

With  existing  technology  for  keyword  or  full-text  retrieval,  any  descriptive  words  contained 
in  the  title  take  on  added  significance.  Consequently,  a  titles  for  software  should  be  de- 
scriptive of  the  major  functions  or  contents  they  are  describing. 

Authorship.  Give  the  full  name  of  author(s),  programmer(s) ,  or  corporate  body  (govern- 
ment agency)  responsible  for  the  intellectual  content  of  the  software.  For  multiple  authors, 
give  proper  name  order. 

Statement(s)  of  responsibility.  Statements  of  responsibility  relate  to  persons  or  cor- 
porate bodies  responsible  for  intellectual  content;  to  corporate  bodies  from  which  the  con- 
tent emanates;  to  personal  or  corporate  sponsorship;  and  to  personal  or  corporate  responsi- 
bility for  the  performance  or  development  of  a  work.    For  books,  statements  of  responsibility 
include  authors,  editors,  writers  of  prefaces  or  introductions,  illustrations,  etc.  For  com- 
puter programs,  statements  of  responsibility  are  used  for  authorship,  but  also  for  contribu- 
ting roles  played  in  the  creation  or  development  of  the  program.    Since  many  of  the  tasks 
associated  with  program  development  may  be  contracted  out  to  another  party,  responsibility 
statements  may  be  used  to  indicate  the  relationship  of  the  work  to  persons  or  corporate 
bodies  that  would  otherwise  not  be  known.  Example: 

Developed  by  the  Center  for  Advanced  Computation,  University 
of  Illinois  for  the  Office  of  Land  Information  and  Analysis, 
National  Aeronautics  and  Space  Administration  (NASA) 
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Edjtlon,  A  program  edition  occurs  when  there  are  major  changes  in  the  programming 
statements,  a  change  in  the  programming  language,  or  other  significant  changes.  Editions 
for  programs  are  usually  designated  in  terms  of  "version,"  "release"  and  "level."  Each 
signifies  to  a  potential  user  that  new  routines,  or  other  enhancements  have  been  made  to 
the  program.  Examples: 

Version  5.20         or        Level  3.4 

In  both  examples  above,  the  term  "release"  is  implied  but  not  stated.  If  it  were  stated,  it 
would  be  "version  5,  release  20"  or  "level  3,  release  4." 

Producer.  A  software  producer  is  defined  as  that  person  or  corporate  body  with  the 
overall  administrative  responsibility  for  bringing  the  program  into  existence. 

Place  of  production.  Give  the  complete  address  (as  judged  appropriate)  for  the  place 
of  production.  The  place  of  production  is  defined  as  the  "main  office"  or  the  location  used 
as  part  of  the  formal  mailing  address.  For  example,  the  place  of  production  for  a  program 
produced  at  the  Bureau  of  the  Census  is: 

Washington,  D.C. 

not 

Suitland,  Md. 

Name  of  personal  or  corporate  producer.  Give  the  personal  or  corporate  producer  of  the 
program.  In  citing  the  appropriate  organization  or  person  responsible  for  the  production  of 
the  program,  indicate  the  full  organizational  title  and  affiliation  as  appropriate. 

Date  of  production.  Production  date  for  a  software  program  is  defined  as  the  date  the 
file  became  operational  in  machine-readable  form  for  analysis  and  processing. 

Distributor.  A  program  distributor  is  defined  as  that  organization  which  has  been 
designated  by  the  author  or  producer  to  reproduce  copies  of  a  particular  program.  If  a 
distributor  is  not  cited,  it  is  assumed  that  the  author  or  producer  is  fulfilling  this 
function. 

Place  of  distribution.  Give  the  complete  geographic  location  of  the  place  of  distri- 
bution, including  address,  zip  code  and  telephone  number. 

Name  of  personal  or  corporate  distribution.  Give  the  personal  or  corporate  name  of  the 
distributor  of  the  program. 

Date  of  distribution.  The  distribution  date  for  a  program  is  defined  as  the  year  the 
program  became  available  for  wide  distribution  to  the  public  or  to  other  agencies.  If  the 
distribution  date  is  not  different  from  the  production  date,  then  it  is  not  given. 

Series  title.  A  program  series  title  is  the  collective  title  under  which  a  program 
is  issued  as  one  of  its  parts.    Like  a  monographic  series  for  printed  material,  the  program 
file  conterpart  may  be  defined  as  a  number  of  separate  program  files  issued  successively  and 
related  in  subject,  purpose,  and  form.  They  are  usually  produced  by  the  same  organization, 
but  may  have  separate  and  distinct  titles.  Such  program-defined  series  should  carry  a 
collective  title  and  be  placed  on  the  title  page  of  the  accompanying  documentation, 

3.  "TITLE  PAGE"  EQUIVALENTS  FOR  SOFTWARE 

Internal  title  page.  Optimally,  a  "title  page"  equivalent  should  be  part  of  the  pro- 
gram itself.  An  internal  title  page  would  be  totally  file-specific  and  could  not  easily  be 
lost  or  separated  from  the  program  it  is  describing.  Upon  receiving  a  program  stored  on  any 
type  of  data  carrier,  the  recipient  could  arrange  for  the  "title  page"  equivalent  to  be 
printed  out  or  displayed  on  a  video/CRT  screen.  The  resulting  descriptive  information  would 
reveal  the  program's  bibliographic  identity  and  any  relevant  information  pertaining  to  its 
edition. 

Internal  user  file  labels.  The  ANSI  X3. 27-1978  -  Magnetic  Tape  Labels  and  File 
Structure  for  Information  Interchange  provides  magnetically  recorded  labels  for  the  pur- 
pose of  identifying  files.  Although  limited  to  magnetic  standard-labeled  tape  files,  an 
option  in  the  standard  establishes  a  User  Header  Label  (UHL)  in  which  space  adequate  for  a 
"title  page"  equivalent  for  computer  software  is  available. 
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A  UHL  consists  of  the  following  fields  of  eighty  character  records: 


CP 

Field  Name 

L 

Content 

1  to  3 

Label  identifier 

3 

UHL 

4 

Label  Number 

1 

"a"  character 

5  to  80 

Reserved  for  User 
Appl i cation 

76 

"a"  characters 

Legend 

CP  -  character  position  in  the  label.    Field  name  -  reference  name  of  the  field. 
L  -  length  of  the  field  (number  of  characters).    Content  -  content  of  the  field 
as  appropriate,    "a"  -  An  "a"  character  is  any  one  of  the  set  of  digits  0,  1,  2, 
...  9,  the  uppercase  letter  A,  B,  C,  .  .  .  Z,  and  the  following  special  charac- 
ters: SP  :"%'()*+,-./:;=?  <> 

A  completed  set  of  UHLs  representing  a  "title  page"  equivalent  for  a  software  program  is 
given  below: 

UHL  1  SYMAP:  Synagraphic  Mapping  System.  Conceived 
UHL  2  and  Developed  by  Howard  T.  Fisher,  Technological 
UHL  3  Institute,  Northwestern  University,  version  5,20 
UHL  4  Produced  by  the  Laboratory  for  Computer  Graphics 
UHL  5  and  Spatial  Analysis,  Harvard  University,  Cambridge, 
UHL  6  Mass. ,  1975. 


User  applied  information  -  characters  5-80 

Label  number  -  1  character  -  position  3 

Label  identifier  -  3  characters  -  position  1-3 

Such  information  once  recorded  should  be  copied  without  change  when  the  program  is  recorded 
on  another  tape.  Information  thus  supplied  should  apply  to  the  identity  of  the  file  and  not 
to  its  physical  characteristics.  Once  supplied  by  a  program  producer,  the  information  should 
not  be  tampered  with  --  like  the  title  page  of  a  book,  it  should  remain  constant, 

From  the  point  of  view  of  bibliographic  control  of  computer  software,  the  use  of  an 
internal  user  label  or  its  equivalent  is  essential.  Motion  pictures  have  title  and  produc- 
tion credits  incorporated  at  the  begining  of  the  picture  frames,  and  sound  recordings  have 
permanent  external  labels  providing  bibliographic  identification.  However,  at  this  stage  of 
their  development,  computer  software  lack  any  i nternal /external  information  or  "title  page" 
equivalent  sufficient  to  identify  the  distinguishing  features  of  specific  titles,  editions, 
and  production  credits. 

One  problem  surrounding  the  use  of  internal  labels  is  compatibility.  Different  compu- 
ters use  different  labeling  devices  that  are  often  not  compatible.  How  problematic  such 
labels  will  prove  to  be  when  considering  the  tranfer  of  a  program  from  one  computer  system 
to  another  is  difficult  to  determine.  There  is  also  the  question  of  how  easily  such  a  label 
could  be  bypassed  by  a  system  which  does  not  read  labels  at  all  or  only  a  particular  type 
of  label.  Thus  the  intent  of  internal  user  labels  to  record  the  equivalent  of  a  title  page 
on  the  file  itself  is  a  useful  goal,  but  it  is  unclear  how  quickly  such  a  system  of  docu- 
mentation will  take  hold.  It  is  hoped  that  appropriate  parties  such  as  the  National  Bureau 
of  Standards  or  the  American  National  Standards  Institute  will  review  this  problem  and  make 
relevant  recommendations.  Perhaps  this  workshop  could  serve  as  the  initial  forum  on  this 
probl em. 
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External  title  page.  The  alternative  to  an  internal  "title  page"  equivalent,  is  to 
rely  on  the  title  page  of  the  accompanying  documentation  to  adequately  describe  the  associ- 
ated program.  However,  program  producers  must  keep  in  mind  that  title  pages  compiled  as 
part  of  the  program's  accompanying  documentation  must  serve  a  dual  function  --  that  is,  the 
information  must  be  sufficient  to  identify  the  printed  documentation,  the  program  being 
described,  and  the  institutional  origins  of  both.  Unlike  the  program  it  is  describing, 
documentation  can  be  functionally  independent.  A  program  on  the  other  hand,  connot  be 
implemented  without  the  aid  of  some  type  of  documentation  --  and  the  linkage  between  the 
two  must  be  maintained.  One  current  practice  that  provides  this  linkage  is  an  introductory 
statement  at  the  top  of  the  documentation's  title  page  indicating  that  the  work  being  de- 
scribed is  a  user's  guide  or  manual  to  be  used  in  conjunction  with  the  program  and  that  the 
information  on  the  title  page  pertains  both  to  the  computer  software  and  its  documentation. 

Edition  statements  for  the  program  must  be  distinguished  from  edition  statements  per- 
taining to  the  program's  documentation,  The  program  file's  edition  statement  precedes  the 
producer  statement  of  the  title  page,  while  the  edition  statement  pertaining  to  the  program's 
documentation  follows  the  program's  producer  statement,  normally  at  the  bottom  of  the  title 
page  Cfigure  1 )  [3], 

4.  CONCLUSION 

What  does  it  mean  for  the  user  when  there  are  no  effective  bibliographic  standards  for 
documenting  computer  software?    A  prospective  user  of  government-produced  software  faces  many 
problems  related  to  identifying  existing  program  resources.    These  problems  exist  in  part 
because  bibliographic  standards  for  computer  software  are  not  yet  enforced.  Bibliographic 
control  consists  of  standards  and  consistent  methods  for  listing  titles,  editions,  and  for 
naming  organizations  responsible  for  producing  them.  Without  these  standard  procedures,  no 
coordinated  system  of  information  services  can  be  created  for  computer  software.  Uniform 
procedures  should  be  developed  for  the  entire  Federal  System,  and  these  procedures  should 
reflect  existing  bibliographic  standards  both  for  programs  and  their  documentation.  Agencies 
must  devote  special  attention  to  the  problems  of  adequate  bibliographic  descriptions  and 
"title  page"  equivalents  for  those  general  purpose  computer  programs  that  they  have  a  mandate 
to  share  with  other  agencies, 
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(User's  Guide  for  Computer  Software) 


SYMAP:  Synagraphic  Mapping  System 

Conceived  and  Developed 
by 

Howard  T.  Fisher 
Technological  Institute  -  Northwestern  University 

version  5.20 

Produced  and  Distributed 
by 

Laboratory  for  Computer  Graphics  and  Spatial  Analysis 
Graduate  School  of  Design  -  Harvard  University 

1975 


User's  Guide  5th  edition 
Revised,  October  1975 
Revised,  May  1976 
Revised,  September  1979 


User's  Guide  Prepared  by  James  D.  Dougenik,  Applications 
Programmer  and  David  E.  Sheehan,  Computer  Cartographer 


Harvard  University       520  Gund  Hall  48  Quincy  Street  Cambridge,  Mass.  02138 

Tel :  (617)  495-2526 


Figure  1:  Suggested  Title  Page  for  Computer  Software  Documentation 
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NBS  FIPS  Software  Documentation  Workshop,  March  3,  1982 


Standards  for  Bibliographic  Control  of  Machine-Readable  Data  Files 

Lenore  S.  Maruyama 

Network  Development  Office,  Library  of  Congress 
Washington,  D.C. 

As  a  prelude  to  a  review  of  certain  standards  in  the  FIPS  series,  standards  in 
the  area  of  automated  bibliographic  control  are  described,  the  most  important  being 
the  American  National  Standard  for  Bibliographic  Information  Interchange  on 
Magnetic  Tape  (ANSI  Z39.2).  This  standard  format  structure  for  machine-readable 
bibliographic  data  has  been  implemented  by  different  bibliographic  applications, 
and  the  implementation  by  the  library  community,  exemplified  by  the  series  of 
formats  known  as  MARC  (Machine-Readable  Cataloging)  that  were  developed  by  the 
Library  of  Congress,  is  discussed.  The  most  recent  format  developed  is  one  for 
machine-readable  data  files  (MRDF) .  The  analysis  and  review  performed  as  the  format 
was  being  compiled  have  resulted  in  questions  being  posed  about  the  elements 
included  in  FIPS  30  (Software  Summary  for  Describing  Computer  Programs  and  Automated 
Data  Systems)  and  in  a  suggestion  for  a  new  standard  to  cover  numeric  data  files. 

Keywords:  ANSI  Z39.2;  Bibliographic  control;  FIPS  30;  Format  structure;  Machine- 
readable  cataloging;  Machine-readable  data  files;  MARC;  MRDF;  Numeric  data  files; 
Software  summary. 

1.  INTRODUCTION 

In  recent  years,  the  importance  of  machine-readable  data  files  or  MRDF  as  an  infor- 
mation resource  has  been  recognized,  largely  because  of  economic  factors.  Costly  dupli- 
cative efforts,  ranging  from  writing  new  software  for  an  accounting  application  to 
collecting  and  creating  machine-readable  statistical  data  on  persons  with  Spanish  sur- 
names, can  be  avoided  if  one  knew,  in  the  first  case,  that  numerous  software  packages  are 
available  commercially  and  are  listed  in  trade  product  directories;  in  the  second  case, 
that  such  a  statistical  data  file  is  compiled  and  distributed  by  the  U.S.  Bureau  of  the 
Census  and  is  listed  in  the  bureau's  Directory  of  Data  Files. 

Bibliographic  control  in  a  library  environment  involves  the  "functions  necessary  to 
generate  and  organize  records  of  library  materials  for  effective  retrieval."  (1)  By 
removing  the  word  "library,"  this  definition  becomes  more  generalized,  and  it  is  within 
this  broader  framework  that  one  can  categorize  the  tasks  involved  in  compiling  the 
inventories  or  directories  mentioned  above  as  bibliographic  control. 

The  purpose  of  this  paper  is  to  provide  an  overview  of  the  standards  associated  with 
automated  bibliographic  control  and  the  application  of  these  standards  at  the  Library  of 
Congress  to  aid  other  institutions  in  their  efforts  to  bring  MRDF  under  bibliographic 
control  as  well  as  to  relate  this  experience  to  a  review  of  a  Federal  Information 
Processing  Standards  (FIPS)  publication.  Documentation  is  not  discussed  separately  here 
because  it  is  assumed  to  be  an  integral  part  of  creating  a  machine-readable  data  file. 


2.  SUMMARY  RECOMMENDATIONS 

In  connection  with  FIPS  30  (Software  Summary  for  Describing  Computer  Programs  and 
Automated  Data  Systems) ,  questions  were  posed  as  to  how  certain  elements  were  used  and 
suggestions  made  for  addition  of  other  elements: 


189 


o 


Would  it  be  useful  to  know  the  name  of  the  person  who  wrote  the  software?  Or  the 
name  of  the  organization,  agency,  or  unit? 


o  Would  it  be  useful  to  know  for  what  agency  the  software  was  written,  as  in  the  case 
of  contractual  work? 

o  Are  the  software  types,  i.e.,  automated  data  system,  computer  program, 
subroutine/module,  sufficient  to  describe  the  program  being  submitted?    Or  sought? 

o  Are  the  technical  details,  i.e.,  computer  manufacturer  and  model,  computer  opera- 
ting system,  programming  language (s),  number  of  source  program  statements,  computer 
memory  requirements,  tape  drives,  disk/drum  units,  and  terminals,  sufficient  when 
looking  for  programs  to  acquire?  Do  users  look  for  programs  by  these  categories, 
e.g.,  programs  written  for  an  IBM  370  in  OS? 

o  Would  a  thesaurus  be  useful  in  supplying  keywords?  In  looking  for  programs  of  a 
certain  type? 

o  Are  there  other  kinds  of  data  that  should  be  provided  to  facilitate  exchange  or 
sharing  of  software? 

Other  activities  in  the  federal  government  are  leading  toward  standardization  of 
elements  to  describe  numeric  data  files.  Development  of  a  new  FIPS  for  description  of 
numeric  data  elements,  taking  advantage  of  the  experience  from  the  effort  coordinated  by 
the  Office  of  Management  and  Budget,  is  needed. 


3.   STANDARDS  FOR  AUTOMATED  BIBLIOGRAPHIC  CONTROL 

This  section  does  not  attempt  to  describe  all  existing  standards  for  automated 
bibliographic  control  but  instead  discusses  the  ones  having  a  significant  effect  on 
information  processing.  Actually,  the  impact  of  these  standards  has  been  far-reaching 
not  only  in  this  country  but  also  abroad  and  in  the  public/private  and  for-profit  and 
not-for-profit  sectors. 

3.1  Format  Structure  for  Machine-Readable  Bibliographic  Data 

The  development  of  the  American  National  Standard  for  Bibliographic  Information 
Interchange  on  Magnetic  Tape  (ANSI  Z39.2)  took  place  in  the  late  1960s.  The  standard 
consisted  of  a  format  structure  that  facilitated  the  implementation  of  certain  capabi- 
lities, such  as  providing  a  vehicle  for  the  exchange  of  records  so  that  only  one  set  of 
conversion  programs  would  be  necessary,  transcribing  variable  length  data  fields  and 
variable  length  data  records,  being  independent  of  any  one  manufacturer's  hardware,  and 
being  independent  of  any  single  programming  language.  When  the  standard  was  first  issued 
in  1971,  these  capabilities  were  considered  innovative.  Even  with  the  considerable 
changes  that  have  taken  place  in  the  computer  industry  and  the  data  processing  field  from 
that  time  to  1979  when  the  standard  was  revised  and  reissued,  these  capabilities  can 
still  be  viewed  as  moderately  difficult  to  provide. 

The  structure  consists  of  three  components:  the  leader,  the  directory  entries,  and 
the  variable  fields.  These  are  summarized  below  to  give  the  reader  an  idea  of  the 
processing  that  would  be  involved  when  handling  records  using  this  structure  (2): 

Leader ;  A  fixed  field,  twenty-four  characters  in  length,  occurring  at  the  beginning  of 
each  record  and  providing  parametric  information  for  the  processing  of  the  record.  Some 
of  the  parameters  include  the  following: 

Record  Length:  A  five-digit  decimal  number  equal  to  the  length  of  the  record, 
including  the  record  length  and  the  record  terminator. 

Status:  A  parameter  indicating  the  relation  of  the  record  to  a  file,  e.g.,  new, 
revised,  or  deleted. 
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Type  of  Record  and  Bibliographic  Level:  Two  parameters  used  together  to  specify  the 
characteristics  and  to  define  the  components  of  the  record.  For  example.  Type  of 
Record  =  Printed  Language  Material;  Bibliographic  Level  =  Serial. 

Indicator  Count:  A  parameter  whose  value  in  the  form  of  a  decimal  digit  is  the 
number  of  indicators  associated  with  each  variable  data  field. 

Identifier  Length:  A  parameter  whose  value  in  the  form  of  a  decimal  digit  is  the 
length  of  the  delimiter  plus  the  data-element  identifier (s)  used  within  the  record. 

Base  Address  of  Data:  A  parameter  whose  value  in  the  form  of  a  five-digit  decimal 
number  specifies  the  character  position  of  the  character  following  the  field  termi- 
nator of  the  directory,  where  the  origin  is  the  first  character  of  the  leader. 

Entry  Map:  A  set  of  parameters  specifying  the  structure  of  the  entries  in  the 
directory  as  follows: 

Length  of  the  Length  of  Field  Portion  of  Each  Directory  Entry 

Length  of  the  Starting  Character  Position  Portion  of  Each  Entry 

Length  of  the  Implementation-Defined  Portion  of  Each  Entry 

(The  tag  is  assumed  to  be  three  digits  in  length.) 

The  other  positions  in  the  leader  are  either  reserved  for  future  use  or  are  reserved 
as  implementation-defined  positions. 

Directory:  A  series  of  fixed  fields  or  entries  providing  an  index  to  the  location  of  the 
variable  fields  within  the  record.    The  entries  consist  of  the  following: 

Tag:  Three  alphabetic  or  numeric  basic  characters.  Tags  whose  first  two  characters 
are  zero  specify  the  control  fields;  other  tags  specify  data  fields. 

Length  of  Field:  The  length  in  the  form  of  a  decimal  number  of  the  variable  field  to 
which  the  entry  corresponds,  including  the  field  terminator  and  any  indicators.  See 
also  Length  of  the  Length  of  Field  Portion  in  the  Entry  Map  above. 

Starting  Character  Position:  The  character  position,  in  the  form  of  a  decimal 
number,  relative  to  the  base  address  of  data  of  the  first  character  in  the  variable 
field  referenced  by  the  entry.  The  first  character  of  the  first  field  following  the 
directory  is  numbered  0.  See  also  Length  of  Starting  Character  Position  in  Entry 
Map  above. 

Implementation-Defined  Portion:  If  present,  contains  information  relative  to  the 
variable  field  referenced  by  the  entry.  See  also  Length  of  Implementation-Defined 
Portion  in  Entry  Map  above. 

Variable  Fields:  Fields  whose  length  is  determined  for  each  occurrence  by  the  length  of 
data  comprising  that  occurrence.    There  are  two  kinds  of  variable  fields: 

Control  Fields:  Variable  fields  containing  parametric  or  other  data  which  may  be 
required  for  the  processing  of  the  record  and  being  specified  by  tags  beginning  with 
two  zeros.  Control  fields  are  comprised  of  data  and  a  field  terminator;  they  do  not 
contain  indicators,  delimiters,  or  data-element  identifiers. 

Variable  Data  Fields:  Containing  bibliographic  or  other  data  not  intended  to  supply 
parameters  for  the  processing  of  the  record.  May  include  indicators,  delimiters, 
and  data-element  identifiers,  as  well  as  data  and  a  field  terminator. 

Indicators:  A  one-character  data  element  which  is  associated  with  a  data  field 
and  which  supplies  additional  information  about  the  field.    When  indicators  are 
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present,  they  are  the  first  data  elements  in  the  field.  See  also  Indicator 
Count  in  the  Leader  above. 


Delimiter:  Symbol  that  is  used  as  an  initiator,  separator,  or  terminator  of 
individual  elements  in  a  variable  data  field. 

Data-Element  Identifiers:  When  used,  each  identifier  should  b^  preceded  by  a 
delimiter,  and  each  identifier  should  precede  the  data  element  it  identifies. 
See  also  Identifier  Length  in  the  Leader  above.  The  delimiter  and  data  element 
identifier  are  combined  to  form  a  symbol  used  to  initiate  and  identify  data 
elements  in  a  variable  data  field. 

Field  Terminator:  A  character  used  to  terminate  each  variable  field  in  the 
record.  For  the  last  data  field,  the  field  terminator  is  followed  by  a  record 
terminator . 

The  structure  embodied  by  Z39.2  has  been  adopted  for  different  bibliographic  appli- 
cations, including  those  of  the  library  community  in  this  country  and  abroad  and  the 
scientific  and  technical  community  under  the  auspices  of  the  Committee  on  Scientific  and 
Technical  Information  (COSATI)  whose  format  specifications  are  used  by  the  National 
Technical  Information  Service,  the  Defense  Documentation  Center,  the  National  Aero- 
nautics and  Space  Administration,  and  the  Dept.  of  Energy  in  their  distribution  of 
machine-readable  records  describing  (mostly)  technical  reports  and  citations  to  journal 
articles.  The  library  implementation  of  Z39.2,  exemplified  in  the  formats  developed  by 
the  Library  of  Congress,  is  described  in  the  following  section. 

At  this  point,  it  is  important  to  note  the  reason  for  different  bibliographic 
applications  and  hence,  different  implementations  of  the  standard  format  structure.  The 
library  community  in  this  country  and  in  several  other  countries  such  as  the  United 
Kingdom,  Canada,  and  Australia  follows  a  set  of  rules  and  guidelines  known  as  the  Anglo- 
American  Cataloguing  Rules.  NTIS,  DDC,  NASA,  and  DOE  follow  the  COSATI  Rules  for 
Descriptive  Cataloging.  The  tags  and  the  contents  of  the  fields,  therefore,  differ 
substantially  as  shown  below: 


COSATI  Format 

220    Unclassified  Title 
240    Classified  Title 
260  Subtitle 


Library  Format 

245$a  Short  Title 

245$b  Subtitle 

260$a  Place  of  Publication 

260$b  Publisher 

260$c  Date  of  Publication 


Even  with  these  differences,  the  task  of  processing  bibliographic  records  is  simplified 
by  the  use  of  the  standard  format  structure.  When  one  considers  the  number  of  different 
bibliographic  files  that  have  to  be  processed  by  the  commercial  data  base  vendors  (i.e., 
Lockheed,  System  Development  Corporation,  and  Bibliographic  Retrieval  Services) ,  the 
availability  and  application  of  such  a  standard  have  had  tremendous  implications. 

Subsequent  to  its  adoption  by  the  American  National  Standards  Institute,  the  format 
structure  was  submitted  and  adopted  as  a  standard  by  the  International  Organization  for 
Standardization  as  ISO  2709.  A  footnote  here  in  terms  of  the  relationship  between  ANSI 
Z39.2  and  the  Federal  Information  Processing  Standards  (FIPS) :  In  the  early  1970s,  work 
had  been  started  to  incorporate  the  standard  format  structure  into  the  FIPS  series. 
There  were,  however,  many  objections  raised  by  certain  agencies  because  of  a  misunder- 
standing as  to  the  relationship  of  the  format  structure  to  internal  formats  (the  struc- 
ture was  for  communications  purposes  only)  ,  the  use  (optional)  ,  and  the  scope  of  the 
records  created  using  the  format  structure  (dependent  on  the  particular  application, 
i.e.,  libraries  were  using  it  for  books,  serials,  films,  etc.,  and  the  users  of  the 
COSATI  format  were  including  technical  reports  and  journal  articles)  .  In  any  event,  the 
agencies  that  would  have  adopted  the  FIPS  guidelines  had  already  adopted  and  implemented 
the  ANSI  Z39.2  standard  so  the  matter  was  dropped. 
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3.2  Other  Standards 

The  distribution  of  machine-readable  bibliographic  records  in  the  standard  format 
structure  was  begun  by  the  Library  of  Congress  in  1969  and  was  probably  one  of  the  first 
major  uses  of  the  American  National  Standard  Code  for  Information  Interchange  (ASCII) . 
To  provide  the  capability  of  representing  all  roman-alphabet  languages  and  the  romanized 
forms  of  nonroman-alphabet  languages,  the  basic  ASCII  set  of  128  characters  was  expanded 
to  180  characters  by  expanding  the  ASCII  7-bit  code  to  an  8-bit  code  for  9-track  tape 
users  and  contracting  it  to  a  6-bit  code  for  7-track  tape  users.  (The  latter  option  was 
discontinued  recently.)  It  should  be  noted  that  this  developmental  work  had  been  taking 
place  at  a  time  when  obtaining  printouts  using  both  uppercase  and  lowercase  alphabetic 
characters  was  not  easy.  Shortly  thereafter,  IBM  began  offering  a  print  train  with  the 
library  character  set  as  an  off-the-shelf  item.  In  recent  years,  several  different  CRT 
terminals  have  been  developed  with  the  capability  of  displaying  the  library  character  set 
in  addition  to  COM  (computer-output-microform)  and  photocomposition  devices  that  can 
produce  "printed"  output  with  the  full  character  set.  Progress,  however,  has  been  much 
slower  for  languages  in  nonroman  alphabets,  both  in  terms  of  standard  character  sets  and 
display/printing  devices. 

Other  standards  that  were  important  in  the  development  of  the  library  applications 
included  codes  for  country,  states,  and  languages  and  representation  of  dates.  Where  a 
standard  existed,  it  was  adopted.  In  other  instances,  the  library  community  worked  with 
other  agencies,  which  included  the  National  Bureau  of  Standards  because  of  its  FIPS 
series,  to  develop  the  standard. 


4.  LIBRARY  OF  CONGRESS  IMPLEMENTATION 

In  the  preceding  section,  it  was  mentioned  that  the  library  community  had  developed 
an  application  for  the  standard  format  structure.  This  work  had  been  initiated  by  the 
Library  of  Congress  and  has  been  referred  to  as  MARC  for  machine-readable  cataloging.  In 
actuality,  the  Library  had  begun  this  effort  as  early  as  the  mid-1960s  and  played  an 
instrumental  part  in  developing  the  format  structure  as  a  standard.  The  fact  that  the  LC 
work  on  a  series  of  formats  preceded  the  development  of  the  standard  has  caused  some 
confusion  in  that  the  MARC  formats  developed  by  the  Library  of  Congress  are  thought  to  be 
synonomous  with  the  format  structure  ANSI  Z39.2.  This  section  describes  the  development 
of  the  MARC  formats  at  the  Library  as  well  as  the  circumstances  and  the  requirements 
being  addressed  in  these  efforts  and  the  effects  of  these  considerations  on  the  format 
for  machine-readable  data  files. 

4.1  Development  of  LC  MARC  Formats 

The  MARC  formats,  as  an  implementation  of  ANSI  Z39.2,  were  developed  by  the  Library 
of  Congress  as  part  of  a  documentation  package  for  a  subscription  service  to  distribute 
cataloging  information  in  machine-readable  form.  This  distribution  process  was  a  contin- 
uation of  a  program  begun  in  1901  for  the  Library  to  sell  3x5  cards  containing  cataloging 
information  to  the  nation's  libraries  and  was  considered  a  major  milestone  in  the  pro- 
gress of  library  automation.  The  formats  and  the  dates  of  their  publication  or  imple- 
mentation include  the  following:  books  (1969)  ,  maps  (1970)  ,  serials  (1970)  ,  films 
(1971),  manuscripts  (1973),  music  (1976),  and  authorities  (1976).  Compilation  of  a 
format  for  machine-readable  data  files  is  in  process. 

From  1969  when  the  distribution  service  for  cataloging  information  in  machine- 
readable  form  was  begun  to  the  present  time,  the  Library  of  Congress  has  created  and 
disseminated  over  2  million  MARC  records.  When  the  service  was  first  started,  most  of 
the  subscribers  could  be  categorized  as  individual  library  systems.  Since  then,  the 
total  number  of  individual  subscribers  has  not  increased  dramatically,  but  the  total 
number  of  users  affected  by  the  MARC  service  has  been  affected  because  of  the  following 
developments:  the  establishment  of  bibliographic  utilities  (organizations  operating 
online  computer  facilities  and  maintaining  large  bibliographic  data  files  to  assist 
libraries  in  their  bibliographic  control  activities)  ;  new  services  taking  advantage  of 
the  availability  of  MARC  records  offered  by  commercial  vendors,  many  of  whom  did  not 
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exist  before  the  advent  of  MARC;  and  bibliographic  agencies  in  other  countries  offering 
various  services  to  libraries  in  their  own  countries  using  the  MARC  records. 

These  developments  have  made  the  format  maintenance  process  considerably  more  com- 
plicated. The  formats  have  to  reflect  the  changing  requirements  in  the  area  of  biblio- 
graphic control,  but  any  changes  made  now  have  to  be  weighed  in  terms  of  their  cost 
(particularly  for  the  subscribers  to  the  distribution  service)  as  opposed  to  their 
perceived  benefits.  In  addition,  these  developments  have  caused  the  MARC  formats  to 
become  truly  "interchange"  in  nature  because  institutions  other  than  the  Library  of 
Congress  are  able  to  create  their  own  machine-readable  records  and  are  in  a  position  to 
transmit  or  distribute  them  to  others.  To  perform  these  tasks,  these  other  institutions 
depend  heavily  on  the  format  specifications  and  other  guidelines  provided  by  the  Library 
of  Congress,  and  these  agencies,  therefore,  have  a  vested  interest  in  the  formats  pro- 
duced by  the  Library. 

4.2  Development  of  MARC  MRDF  Format 

The  MARC  format  for  machine-readable  data  files  is  unique  among  its  companion 
formats  in  that  the  Library  of  Congress  has  taken  the  responsibility  to  develop  the 
format  but  has  no  expectation  of  collecting  MRDF  and  placing  them  under  bibliographic 
control  in  the  near  future.  In  other  words,  cataloging  records  for  MRDF  would  not  be 
originating  from  the  Library  of  Congress.  This  would  place  the  burden  of  identifying  new 
requirements  or  changes  in  the  format  on  the  outside  users. 

In  compiling  this  format,  the  Library  followed  a  procedure  instituted  with  the 
compilation  of  the  earlier  formats  to  appoint  a  working  group  of  experts  to  assist  with 
the  work.  Their  expertise  was  heavily  weighted  toward  statistical  data  files,  partly 
because  it  was  in  this  area  from  which  most  of  the  interest  in  bibliographic  control  was 
originating.  The  review  process,  however,  was  extensive  throughout  the  library  and 
information  communities  and  entailed  sifting  and  merging  comments  that  were  often  contra- 
dictory from  librarians  who  knew  nothing  about  machine-readable  data  files,  librarians 
who  knew  the  MARC  formats  but  nothing  about  MRDF,  MRDF  experts  and  data  archivists  who 
knew  nothing  about  the  MARC  formats,  and  several  other  combinations. 

Because  bibliographic  control  of  MRDF  is  still  in  its  infancy,  the  process  of 
identifying  elements  to  be  included  in  the  format  was  not  an  easy  one.  The  products 
(e.g.,  directories,  data  inventories,  etc.)  issued  by  agencies  like  the  Bureau  of  the 
Census,  the  Geological  Survey,  the  National  Technical  Information  Service,  or  the 
national  laboratories  under  the  Dept.  of  Energy  were  consulted.  During  the  review 
process,  questions  were  raised  about  many  of  the  elements  derived  from  the  inventories 
and  directories,  and  these  will  be  described  in  greater  detail  in  the  following  section. 
There  was,  however,  one  problem  that  should  be  mentioned  here.  Machine-readable  data 
files  have  been  viewed,  at  least  in  the  library  world,  as  .a  single  form  of  material  when 
in  fact  they  consist  of  at  least  four  types  (numeric  files,  text  files,  computer  pro- 
grams, representational,  including  graphic)  and  even  more  when  one  considers  sub- 
categories or  combinations  of  these  types.  Each  type  of  file  has  unique  requirements 
that  are  not  shared  with  the  others.  For  example,  information  about  the  kind  of  computer 
system  or  memory  requirements  is  essential  to  have  for  software  but  is  usually  un- 
important for  statistical  data  files.  We  had  considerable  difficulty  in  communicating  to 
the  library  and  information  communities  the  needs  of  all  types  of  MRDF  users  within  the 
framework  of  a  single  document  that  was  coherent  to  everybody. 


5.  RELATED  FIPS  ACTIVITIES 

The  analysis  performed  as  part  of  identifying  elements  needed  for  bibliographic 
control  of  machine-readable  data  files  has  raised  certain  questions  concerning  standards 
issued  in  the  FIPS  series.  This  section  discusses  these  problems  with  regard  to  FIPS  30 
(Software  Summary  for  Describing  Computer  Programs  and  Automated  Data  Systems)  and 
proposes  a  new  standard  for  numeric  data  files. 
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5.1  FIPS  30 


This  standard  was  used  during  the  compilation  of  the  Library  of  Congress  MARC  format 
for  machine-readable  data  files  to  assist  in  identifying  elements  needed  to  describe 
software.  Questions  were  posed,  from  a  library  orientation,  as  to  how  certain  elements 
were  used;  in  addition,  it  was  felt  that  other  elements  that  are  usually  provided  as  part 
of  the  cataloging  process  might  also  be  useful  for  this  standard. 

o  Would  it  be  useful  to  know  the  name  of  the  person  who  wrote  the  software?  Or  the 
name  of  the  organization,  agency,  or  unit? 

o  Would  it  be  useful  to  know  for  what  agency  the  software  was  written,  as  in  the  case 
of  contractual  work? 

o  Are  the  software  types,  i.e.,  automated  data  system,  computer  program, 
subroutine/module,  sufficient  to  describe  the  program  being  submitted?    Or  sought? 

o  Are  the  technical  details,  i.e.,  computer  manufacturer  and  model,  computer  opera- 
ting system,  programming  language(s),  number  of  source  program  statements,  computer 
memory  requirements,  tape  drives,  disk/drum  units,  and  terminals,  sufficient  when 
looking  for  programs  to  acquire?  Do  users  look  for  programs  by  these  categories, 
e.g.,  programs  written  for  an  IBM  370  in  OS? 

o  Would  a  thesaurus  be  useful  in  supplying  keywords?  In  looking  for  programs  of  a 
certain  type? 

o  Are  there  other  kinds  of  data  that  should  be  provided  to  facilitate  exchange  or 
sharing  of  software? 

5.2  Need  for  New  FIPS 

Under  the  aegis  of  the  Statistical  Policy  Division,  Office  of  Information  and 
Regulatory  Affairs,  Office  of  Management  and  Budget  (formerly  the  Office  of  Federal 
Statistical  Policy  and  Standards,  Dept.  of  Commerce) ,  activities  have  been  proceeding  to 
identify  public-use  data  files  available  from  federal  agencies.  These  activities  have 
culminated  in  the  issuance  by  the  National  Technical  Information  Service  of  a  Directory 
of  Federal  Statistical  Data  Files.  The  efforts  involved  in  compiling  this  directory  are 
described  in  a  recent  article  by  J.  Timothy  Sprehe  of  the  Statistical  Policy  Division. 
(3) 

One  of  the  results  of  this  activity  has  been  a  proposed  directive  from  0MB  for  use  by 
federal  agencies  involved  in  creating  and  distributing  statistical  data  files.  With  a 
tentative  title  "Directive  for  Standardized  Abstracts  of  Public  Use  Statistical  Machine 
Readable  Data  Files,"  it  would  appear  to  be  a  logical  starting  point  for  a  FIPS  publi- 
cation. Of  particular  interest  is  the  fact  that  the  proposed  directive  (and  the  direc- 
tory compiled  from  data  supplied  by  this  directive)  emphasize  the  use  of  bibliographic 
standards  to  facilitate  the  merging  of  these  data  with  other  bibliographic  resources. 


6.  CONCLUSIONS 

Bibliographic  control  is  not  an  end  in  itself  and  cannot  operate  in  a  vacuum.  With 
budget  cuts,  the  sharing  of  resources,  in  this  case  of  software,  will  probably  accelerate 
in  the  next  few  years.  It  will  be  important  not  only  to  provide  the  necessary  data  to 
describe  the  software  but  also  to  be  aware  of  the  tools  available  that  list  software  that 
could  be  exchanged  or  acquired.  Workshops  like  this  one  are  essential  to  bring  the  two 
players  together:  the  creators  of  the  software  and  the  documentation  and  the  outside 
users  of  the  software  and  documentation.  The  creators  will  continue  to  create  software 
and  documentation  to  meet  their  own  needs  but  with  the  knowledge  that  if  they  follow 
standards,  they  will  facilitate  the  sharing  process.  Users  of  the  (acquired)  software 
should  also  be  able   to  communicate   their   needs  and  problems   in  connection  with  the 
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packages  they  receive  and  the  usefulness  of  the  data  provided  in  announcing  software 
availability. 
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The  Computer  Program  Abstract  as  Software  Documentation* 

Margaret  K.  Butler 

National  Energy  Software  Center 
Argonne  National  Laboratory 

The  computer  program  abstract,  while  not  universally  accepted  as  a  form  of 
software  documentation,  has  long  been  recognized  as  a  necessary  reference  docu- 
ment by  the  computer  user  community.    Users  have  banded  together  in  cooperative 
organizations  with  like  computing  environments,  common  disciplines,  or  a  shared 
need  for  particular  applications  software,  to  promote  the  use  of  computer  pro- 
gram abstracts  as  a  means  of  publication,  program  exchange,  and  software  devel- 
opment cost  savings.    Compilations  of  program  abstracts  have  been  adopted  to 
describe  the  contents  of  computer  program  libraries  and  to  market  the  software 
industry's  products. 

In  1981,  publication  of  an  American  National  Standard  for  Computer  Program 
Abstracts  was  approved,  lending  an  air  of  respectability  to  the  abstract's  claim 
to  a  place  in  the  software  documentation  family.    This  paper  first  seeks  to 
define  a  computer  program  abstract  and  to  point  out  its  distinguishing  features. 
Then,  users  and  proponents  of  computer  program  abstracts  are  identified,  and 
prior  standardization  efforts  are  reviewed,  followed  by  a  discussion  of  the 
development  of  the  American  National  Standard. 

Keywords:  Computer  program  abstracts;  Software  documentation;  Standards; 
Information  systems. 

1.  INTRODUCTION 

In  most  dictionaries  you  will  find  among  the  various  definitions  attributed  to  the 
noun  abstract,  something  similar  to  the  following: 

"a  summary  of  a  statement,  document,  speech,  etc;  that  which  concentrates  in 
itself  the  essential  qualities  of  anything  more  extensive  or  more  general,  or 
of  several  things;  essence" 

It  is  in  this  sense  that  the  term  computer  program,  or  software,  abstract  has  been 
applied  to  the  form  of  software  documentation  discussed  in  this  paper.    A  computer  program 
abstract  is  a  computer  program  summary,  software  documentation  which  conveys  to  the  reader 
the  essential  qualities  of  the  computer  program,  such  as  the  nature  of  the  information- 
processing  functions  performed  or  the  physical  problem  solved  and  the  computing  environ- 
ment required. 

To  better  understand  the  position  the  abstract  fills  in  the  software  documentation 
line,  a  number  of  characteristics  peculiar  to  the  computer  program  abstract  are  listed 
below.    The  abstract  — 

•  functions  as  an  introductory  or  "awareness"  document.    It  is  usually  the  reader's 
initial  contact  with  the  software. 

•  is  the  documentation  most  frequently  overlooked  by  the  author  or  software  develop- 
ment project. 

•  is  often  omitted  from  the  documentation  requirements  specified  by  the  sponsor,  or 
funding  organization. 

*Work  performed  under  the  auspices  of  the  U.  S.  Department  of  Energy. 
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•  is  the  primary  concern  of  computer  user  organizations  and  government  programs  dedi- 
cated to  "software  sharing"  and  "technology  transfer."    Compilations  of  abstracts 
serve  as  reference  catalogs  to  computer  program  libraries  and  software  collections. 

•  appears  routinely  in  the  guise  of  a  product  announcement  or  description  from  compu- 
ter manufacturers  and  software  houses.    In  addition,  catalogs  of  abstracts  and  soft- 
ware directories  are  marketed  as  information  service  products  and  reference  volumes. 

•  is,  by  definition,  a  concise  document  readily  transformed  into  machine-readable 
documentation. 

•  functions  as  a  reference  document.    Its  main  purpose  is  to  provide  its  readers,  a 
segment  of  the  computer  user  population,  with  sufficient  information  about  the  compu- 
ter program  for  them  to  judge  the  appropriateness  of  the  software  to  their  needs  and 
available  resources.    When  compilations  of  abstracts  are  stored  as  computer  data- 
bases, retrieval  is  improved  by  indexing  and  use  of  automated  search  strategies. 

2.  USAGE 

Use  of  the  abstract  as  a  form  of  software  documentation  has  been  promoted  for  the  most 
part  by  three  categories  of  computer  user  organizations  and  the  software  and  service  compo- 
nents of  the  computer  industry.    The  first  category  of  user  organization  is  the  computer 
manufacturer's  users  group,  typified  by  IBM's  SHARE  and  Digital  Equipment  Corporation's 
DECUS.    Computer  program  abstracts  first  found  favor  with  these  organizations.    In  1954, 
when  IBM  set  up  an  IBM  650  Program  Library  at  its  World  Headquarters  in  New  York  City,  all 
IBM  650  installations  were  encouraged  to  submit  locally-developed  software  accompanied  by  an 
abstract  describing  their  contribution.    A  year  later  when  SHARE,  the  first  computer  users 
group,  was  formed  by  a  group  of  IBM  701  users,  one  of  its  first  acts  was  to  establish  a  for- 
mal program  exchange  for  its  members  with  abstracts  describing  each  program.    As  additional 
computer  users  groups  came  into  existence,  the  other  manufacturers  agreed  to  staff  and  main- 
tain similar  program  exchange  facilities  and  to  publish  abstracts  describing  the  contributed 
software,  realizing  the  potential  benefits  of  such  information  to  their  marketing  operations. 
The  importance  of  user-group  exchange  efforts  has  declined  over  the  years  with  the  "unbun- 
dling" of  hardware  and  software,  the  emergence  of  a  viable  computer  software  industry,  and 
the  shift  from  predominantly  scientific  and  engineering  applications  in  a  free-exchange, 
research  and  development  setting  to  mostly  commercial  applications  in  a  proprietary 
business  environment. 

The  second  category  of  computer  user  organizations  consists  of  government  agencies 
and  contractors.    The  Atomic  Energy  Commission  (AEC)  and  its  successors  -  the  Energy 
Research  and  Development  Administration,  the  Nuclear  Regulatory  Commission,  and  the 
Department  of  Energy  (DOE)  -  are  in  this  class,  along  with  the  National  Aeronautics  and 
Space  Administration  (NASA),  the  National  Technical  Information  Service  (NTIS),  and  the 
General  Services  Administration  (GSA).    The  AEC  in  1955,  in  what  was  probably  the  earliest 
government  action  to  promote  software  sharing,  published  a  compilation  of  abstracts  of 
available  digital  computer  codes  for  nuclear  reactor  problems  [1].    The  agency  and  its 
successors  have  been  publishing  abstracts  of  agency-developed  software  ever  since  in  the 
interest  of  software  sharing  and  the  elimination  of  redundant  development  costs.  In 
1960,  the  Argonne  Code  Center,  a  software  exchange  and  information  center,  was  created  to 
handle  the  publication  of  abstracts  and  the  maintenance  and  dissemination  of  nuclear 
reactor  codes.    The  Center  has  since  been  renamed  the  National  Energy  Software  Center 
(NESC),  handles  DOE-developed  software,  and  the  abstracts,  in  machine-readable  form,  have 
been  added  to  the  DOE  Technical  Information  Center's  RECON  system. 

In  1966,  NASA  established  COSMIC,  a  center  for  the  dissemination  of  NASA-developed 
software,  at  the  University  of  Georgia.    Government  use  of  computer  program  abstracts 
was  dominated  until  the  seventies  by  the  activities  of  these  two  centers  and  the  AEC's 
specialized  Radiation  Shielding  Information  Center  at  Oak  Ridge  National  Laboratory.  Then 
in  1974,  the  Department  of  Commerce's  NTIS,  which  is  charged  with  making  the  results  of 
federally-sponsored  research  and  development  available  to  the  public,  began  to  include 
abstracts  of  federally-generated  machine-readable  data  files  and  software  along  with  the 
abstracts  of  agency  reports  it  publishes.    Since  1977,  NTIS  has  also  published  for  the 
GSA  the  Federal  Software  Exchange  Program  catalog,  which  contains  abstracts  of  the 
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federally-produced  common-use  software  available  to  federal  agencies,  and  state  and  local 
governments  under  that  program. 

Professional  societies,  trade  associations,  and  other  special  interest  groups,  such  as 
the  American  Nuclear  Society,  the  Society  for  Computer  Applications  in  Engineering,  Plan- 
ning, and  Architecture,  and  the  Quantum  Chemistry  Program  Exchange  make  up  the  third 
category  of  user  organizations  who  have  endorsed  the  use  of  the  abstract.    As  early  as  1956, 
the  Nuclear  Codes  Group  (NCG),  an  organization  which  later  became  the  Mathematics  and 
Computation  Division  of  the  American  Nuclear  Society,  adopted  a  standard  abstract  format 
for  the  use  of  its  members,  and  in  1959,  the  NCG  published  a  collection  of  their  abstracts 
in  the  Communications  of  the  Association  for  Computing  Machinery  [2].    A  supplementary 
listing  appeared  in  the  same  periodical  the  following  year  [3]. 

As  the  computer  software  industry  developed,  product  announcements,  computer  program 
abstract  catalogs,  and  software  directories  became  a  popular  means  of  marketing  the  software 
vendors'  wares.    They  appear,  too,  as  products  in  their  own  right  -  the  offerings  of 
publishing  and  information  service  firms,  such  as  International  Computer  Programs,  Datapro 
Research  Corporation,  and  Auerbach  Publishers. 

3.  STANDARDIZATION 

The  initial  computer  program  abstract  standard  was  included  in  a  computer  program 
documentation  standard  developed  by  a  study  group  composed  of  members  of  the  American 
Nuclear  Society's  Mathematics  and  Computation  Division.    This  group,  identified  as  the 
STICE  Committee  for  STudy  In  Cooperative  Efforts,  started  out  in  mid-1965  to  write  a  com- 
prehensive documentation  standard  for  scientific  and  engineering  applications  software. 
Because  of  a  general  reticence  to  impose  too  detailed  and  costly  a  documentation  require- 
ment on  the  program  author  and  the  developing  installation,  a  significant  fraction  of  the 
resulting  Society  standard  was  devoted  to  the  computer  program  abstract  [4]. 

In  May  of  1968,  having  explored  standardization  of  computer  program  libraries  at  the 
behest  of  the  Council  of  the  Association  for  Computing  Machinery,  the  Joint  Users  Group 
(JUG)  Program  Library  Committee  submitted  a  proposed  standard  to  the  American  National 
Standards  Committee  Z39  on  Library  Work,  Documentation,  and  Related  Publishing  Practices. 
Their  proposal,  "Field  Headings  and  Codes  for  Machine-Sensible  Computer  Program 
Descriptions,"  was  based  on  conventions  defined  for  the  submittal  of  program  descriptions 
to  the  JUG  Program  Library  Catalog  [5].    The  proposal  was  referred  to  SPARC/DOCN,  an  ad  hoc 
Committee  on  Documentation  set  up  under  the  X3  Standards  Planning  and  Requirements  Commit- 
tee (SPARC)  to  study  the  need  for  and  the  feasibility,  cost,  and  benefits  of  developing  a 
national  standard  on  program  abstracts.    As  part  of  their  study  SPARC/DOCN  designed  a 
questionnaire  to  solicit  the  opinions  of  selected  members  of  the  data  processing  community. 
On  the  basis  of  the  survey  responses  and  the  committee's  deliberations,  a  suggested 
scope  and  program  of  work  for  an  X3  standards  development  project  on  computer  program 
abstracts,  along  with  recommendations  that  a  new  technical  committee  be  formed  to  develop 
the  standard  and  that  the  JUG  proposal  be  viewed  as  only  one  of  a  number  of  models  to  be 
considered,  were  transmitted  to  SPARC  in  late  1971.    However,  it  was  not  until  early  in 
1974  that  Project  211  on  Computer  Program  Abstracts  was  approved  by  the  American  National 
Standards  X3  Committee  on  Computers  and  Information  Processing,  and  it  was  September  1975 
by  the  time  Technical  Committee  X3K7  was  able  to  start  work. 

During  the  1971  to  1975  period,  while  little  progress  was  made  in  the  X3  arena,  an 
extensive  revision  of  the  American  Nuclear  Society's  documentation  standard  prepared  by 
the  Society's  ANS-10  subcommittee  was  adopted  as  an  American  National  Standard  [6],  and 
the  leadership  role  in  the  federal  government's  ADP  standards  program  was  assumed  by  NBS 
and  its  Institute  for  Computer  Sciences  and  Technology  [7].    Federal  Information 
Processing  Standards  (FIPS)  Task  Groups  were  organized  to  assist  the  NBS  in  the  develop- 
ment, adoption,  and  implementation  of  needed  standards.    One  of  these,  FIPS  Task  Group  14, 
assigned  the  task  of  developing  standards  and  guidelines  for  the  documentation  of  indi- 
vidual computer  programs,  automated  data  systems,  and  information  processing  systems,  was 
given  as  its  first  priority  the  documentation  of  abstracts.    The  Task  Group  developed  a 
standard  software  summary  form,  together  with  instructions,  for  describing  computer  programs 
and  automated  data  systems  for  identification,  reference,  and  dissemination  purposes.  The 
form  and  instructions  appeared  as  a  FIPS  publication,  FIPS  Pub  30,  dated  June  30,  1974  [8]. 
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The  Committee  spent  many  meetings  refining  the  list  of  information  items  to  be  included 
in  the  standard  and  defining  their  content.    A  division  of  the  list  into  "required"  and 
"optional"  items  was  investigated,  as  was  the  concept  of  a  mini-abstract,  or  subset,  to 
facilitate  machine  storage,  search,  and  retrieval.    Upon  examination,  because  of  the  diverse 
needs  specific  to  various  segments  of  the  computing  community,  both  the  mini-abstract  concept 
and  the  rigorous  classification  of  "required"  versus  "optional"  items  were  abandoned.  In- 
stead, committee  members  agreed  to  the  use  of  standard  headings  and  a  common  set  of  items. 
Broad  definitions  were  drafted  for  many  items  in  an  effort  to  encompass  most  of  the 
frequently-expressed  needs.    The  more  parochial  needs  remaining  were  accommodated  by 
allowing  supplementary  information  items. 

The  sequencing  of  information  items  was  discussed  both  in  relation  to  the  order  in 
which  items  are  defined  in  the  standard  and  to  the  positioning  of  the  supplementary  items. 
A  standard  ordering  is  desirable  from  the  user  point  of  view,  particularly  when  abstracts 
from  a  number  of  sources  are  being  consulted.    Several  ordering  methods  were  considered, 
such  as  library  search  techniques  and  classification  schemes.    The  positioning  of  supple- 
mentary items  in  relation  to  the  standard  items  was  debated.    It  was  recognized  that  while 
interspersing  supplementary  items  would  permit  grouping  of  related  information,  all  stand- 
ard items  must  precede  supplementary  items  for  uniformity.    Omissions  of  information  are 
then  readily  apparent,  and  supplementary  information  is  easily  recognized. 

In  September  of  1977  the  sixth  draft  of  the  standard,  containing  the  24  information 
items  shown  in  Table  II,  was  circulated  to  over  500  identified  users  of  computer  program 
abstracts  for  review.    Ninety-six  of  the  reviewers  responded  with  suggestions,  praise,  and 
criticism.    All  of  the  comments  received  were  considered  during  subsequent  X3K7  meetings. 

Table  II 

DRAFT  6  INFORMATION  ITEMS 


1 . 

Category 

9. 

References 

17. 

Operating  System 

2. 

Keywords 

10. 

Programming  Language 

18. 

Related  and  Associated  Software 

3. 

Identification 

11. 

Program  Type 

19. 

Communications 

4. 

Abstract  Date 

12. 

Program  Size 

20. 

Material  Available 

5. 

Program  Status 

13. 

Processing  Modes 

21 . 

Acquisition 

6. 

Program  Date 

14. 

Timing 

22. 

Distribution  Restrictions 

7. 

Narrative  Description 

15. 

Hardware 

23. 

Contact 

8. 

Method  of  Solution 

16. 

Storage  Requirements 

24. 

Responsible  Organization 

A  number  of  changes  in  the  standard  resulted  from  these  discussions.    The  final  docu- 
ment approved  by  the  American  National  Standards  Institute  (ANSI)  on  March  9,  1981  con- 
tains just  22  information  items;  items  19  and  22  of  the  sixth  draft  were  dropped  and  the 
definitions  of  other  items  expanded  to  include  that  information.    The  titles  "References" 
and  "Material  Available"  were  modified  to  "Bibliographic  References"  and  "Program  Material 
and  Support  Available,"  respectively,  to  more  specifically  identify  their  intended  contents. 
The  order  in  which  the  items  appear  was  revised  slightly;  "Bibliographic  References"  was 
placed  in  the  position  formerly  filled  by  "Communications."    Then,  in  1978,  the  Committee 
decided  to  add  an  Appendix  containing  an  abstract  for  a  scientific  application,  and  one 
for  a  business  application,  to  illustrate  use  of  the  standard.    Later,  a  third  abstract 
for  a  computer  manufacturer's  software  product  was  included  to  represent  the  software 
industry  environment. 

Copies  of  the  computer  program  abstract  standard  have  been  available  from  ANSI  since 
August  of  1981.    Upon  adoption  of  the  standard  by  the  producers  of  computer  program  ab- 
stracts, the  abstract  should  win  acceptance  as  a  form  of  software  documentation,  and  when 
accepted,  hopefully,  two  of  the  abstract  characteristics  presented  in  the  Introduction  can 
be  changed  to  show  the  abstract  — 

•  is  the  documentation  most  frequently  prepared  by  the  author  or  software 
development  project. 

•  is  always  included  in  the  documentation  requirements  specified  by  the  sponsor, 
or  funding  organization. 
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At  its  first  meeting,  X3K7  reviewed  the  scope  and  program  of  work  assigned  the  project 
and  discussed  the  existing  standards.    Endorsement  of  the  FIPS  summary  guideline,  or  a  modi- 
fication thereof,  as  an  X3  standard  was  considered.    To  ensure  that  the  standard  proposed 
would  accommodate  the  needs  of  the  entire  computing  community  insofar  as  practicable,  the 
committee  decided  to  collect  and  study  the  computer  program  abstracts  in  current  use.  A 
letter  was  sent  to  over  fifty  organizations  and  firms,  known  to  produce  abstracts  or  soft- 
ware summaries,  requesting  samples  of  their  abstracts  together  with  author's  instructions  or 
related  material  pertinent  to  the  committee's  needs.    Sample  abstracts  were  obtained  from 
46  producers;  29  of  these  were  government  sources.    Seven  examples  were  supplied  by  pro- 
fessional societies  or  other  special  interest  organizations;  five  came  from  commercial  firms 
and  five  from  computer  user  groups. 

Data  taken  from  these  sample  abstracts  were  analyzed  to  measure  the  importance  attri- 
buted to  various  information  items  by  the  abstract  producers,  to  identify  the  headings,  or 
titles,  most  frequently  associated  with  the  different  information  items,  and  to  ascertain 
the  applicability  of  the  items  to  the  four  environments  represented  in  the  study.    To  do 
this,  the  titles,  or  headings  of  all  of  the  information  items  used  in  the  46  sample  ab- 
stracts were  transcribed  into  machine-readable  form  and  aggregated  into  53  canonical  head- 
ings, so  that  the  number  of  occurrences  of  each  heading  could  be  tabulated  as  a  measure  of 
the  importance  of  the  associated  composite  information  item.    This  did  not  encompass,  how- 
ever, those  instances  in  which  the  information  item  was  included  as  secondary  information 
(i.e.,  subsumed  under  another  title  and  different  canonical  heading).    Those  occurrences 
were  tabulated  separately.    Table  I  shows  the  number  of  both  primary  and  secondary 
occurrences  for  the  abstract  information  items  studied  by  X3K7. 

Table  I 

IMPORTANCE  OF  ABSTRACT  INFORMATION  ITEMS  MEASURED  BY  FREQUENCY  OF  OCCURRENCE 


Titi e  Primary      Secondary  Title 


Available  Material 

Category 

Cost 

Data  Base  or 

Data  File 
Date: 

abstract 

program  or  revision 

other 
Documentation 
Hardware: 

general 

computer 

disk/drum 

memory 

peripheral s 

printer 

punch 

reader 

special 

tape  units 

terminal 
Identification: 

general 

abbreviated  name 

name 

number 
Input  and  Output 
Keywords 
Language 


14 

23  4 

11  2 

4  1 

10  1 

10  2 

8  1 

17  3 

13  1 

28  4 

2  3 
13  3 

9  1 
1  2 
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It  is  suggested  that  the  ANSI  X3.88  Computer  Program  Abstract  be  considered  as  a 
replacement  for  the  present  FIPS  Pub  30.    The  format  of  the  ANSI  standard  is  more 
flexible.    Additional  information  items  identified  as  important  to  the  abstract-user 
community  are  included,  such  as  "Method  of  Solution,"  "Timing,"  "Related  and  Associ- 
ated Software,"  and  "Bibliographic  References,"  and  documentation  of  more  detail  is 
encouraged  in  other  items,  particularly  in  regard  to  the  specific  material  available 
and  the  means  of  acquiring  that  material. 
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The  text  fornatter  can  serve  as  a  powerful  tool  for  manipulating     text     of  all 
types.     Techniques  are  described  for  using  a  single  body  of  machine-readable  text  to 
generate     questionnaires,     data     dictionaries,     data  editing  materials,  and  archival 
documentation  for  machine-readable  data  files. 
'    Keywords:  Data  documentation;  text  formatters. 


1.     TEXT  FORIIATTIIIG  PROGRAIIS 


An  indirect  text  formatting  program  with  a  macrocommand  facility  and  the  ability  to 
link  to  high-level  language  subroutines  can  be  used  as  the  basis  of  a  generalized 
documentation  system.  Although  the  University  of  British  Columbia's  Format  program  is  used 
in  the  implementation  described  here,  any  other  formatter  with  the  necessary  characteristics 
will  do  equally  well. 


1.1.     Indirect  text  formatters 


An  "indirect"  text  processor  is  one  which  accepts  as  input  a  file  containing  text  and 
formatting  commands,  and  produces  an  output  file  of  formatted  text.  An  indirect  text 
formatter  can  be  contrasted  to  a  "direct"  or  "what  you  see  is  what  you  get"  formatter,  vjhich 
produces  formatted  text  as  it  is  entered.  (Direct  formatters  are  seen  only  on  micro 
computers  or  dedicated  word  processors.)  An  indirect  text  formatter  has  botVi  global  and 
local  commands.  An  example  of  a  global  command  in  Format  is  "width  65",  which  sets  a  text 
line  width  of  65  characters  from  the  point  of  invocation  to  the  end  of  the  document  or  to 
the  next  "width"  command.  An  example  of  a  local  command  in  Format  is  "/I/",  v/hich  indicates 
that  a  new  line  is  to  be  started  at  that  point.  Unlike  many  indirect  text  processors. 
Format  does  not  require  that  local  commands  be  in  any  particular  position  in  the  input  line, 
llany  text  formatters  require  that  all  command  operands  be  on  a  line  by  themselves. 


1.2.     I  lac  r  OS 


Format  allows  the  definition  of  macro  commands  with  substitution  of  up  to  ten 
parameters.  An  example  of  a  macro  command  with  an  argument  is  "|h2"  which  generated  the 
heading  for  the  first  section  of  this  paper.     The  macro  is  defined 

/w612m/    |count(h2)|.     /C/|par.l|    /nC/   1  contents ( | par . 1 |  , 1 ) 


An  example  of  the  macro's  invocation  is 
lh2('Text  formatting  programs') 


The  expansion  of  the  macro  puts  the  definition  into  the  program's  input  stream  with  the 
text  argument  substituted  for  the  parameter  string  in  the  definition.  The  macro  starts  a 
new  page  if  less  than  six  lines  remain  on  the  current  page  ("v/6").  If  not  at  the  top  of  a 
page,  it  skips  two  lines  ("12"),  begins  centering  ("m"),  prints  and  then  increments  a 
counter  named  for  the  heading  (" | count (h2) |  .")  .  The  macro  then  prints  the  argument 
converted  to  upper  case  ("C"),  turns  off  uppercase  conversion  and  centering  and  starts  a 
paragraph  ("Omp").     Finally,  the  macro  makes  an  entry  into  the  table  of  contents. 


*The  author  was  unable  to  present  this  paper  at  the  workshop. 
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1.3.  Functions 

Although  the  syntax  of  a  Format  function  call  is  similar  to  a  macro  invocation,  a 
function  is  quite  different  in  definition  and  operation.  Host  format  functions  are  compiled 
FORTRAN  subroutines  which  are  dynamically  loaded  at  execution  time.  The  contents  function 
builds  a  queue,  each  of  whose  elements  is  a  macro  containing  the  text,  the  current  page 
number,  and  a  number  indicating  the  level  of  indentation  of  the  contents  item.  At  the  end 
of  the  document,  the  contents  queue  is  fed  into  the  input  stream  and  expanded  to  yield  a 
table  of  contents.  The  ability  to  load  FORTRAN  subroutines  allows  for  an  almost  arbitrarily 
great  expansion  of  the  text  formatter  tjhile  maintaining  its  or"-ginal  syntax.  Built-in 
format  functions  include  such  things  as  calls  to  the  systc;m  time  and  date  routines,  a 
variety  of  alphabetic  and  numeric  counters,  and  stack  utilities  such  as  tables  of  contents 
and  indices . 

1.4.  Libraries 

Document  processors  usually  have  both  built-in  and  user-supplied  libraries  of  macros 
and  functions.  The  ability  to  handle  multiple  libraries  is  helpful,  in  order  to  define 
alternate  expansions  of  macrocommands . 

2.     IIACRO  AND  FUNCTION  USAGE 

The  original  use  of  macros  was  as  a  shorthand,  to  avoid  the  repetition  of  long  strings 
of  commands  in  recurring  items  such  as  headings.  It  is  certainly  easier  to  type  "|h4"  than 
the  long  string  of  commands  and  function  calls.  In  addition,  a  set  of  macros  imposes  a 
stylistic  discipline.  A  well  chosen  set  of  macro  names  allows  an  easy  transition  between 
related  syntactic  forms.  Thus,  although  a  level  three  heading  nay  be  quite  different  in 
syntax  from  a  level  four  heading,  the  manuscript  change  from  one  to  the  other  is  simple  and 
straight  forward . 

Finally,  and  most  important,  the  invocation  of  the  macro  can  be  separated  from  its 
definition.  The  American  Psychological  Association  uses  four  levels  of  heading  which  differ 
in  capitalization,  centering,  etc.  Otn^r  learned  societies  employ  different  conventions, 
e.g.,  the  numbered  paragraphs  used  in  this  paper.  In  most  cases,  the  logical  structure  of  a 
document  is  independent  of  the  stylistic  conventions  used  in  its  publication.  Thus,  the 
arbitrary  macro  names  "|hl",  "|h2",  "|h3",  and  "|h4"  can  be  expanded  according  to  any  manual 
of  style.  In  cases  where  a  stylistic  format  does  not  allow  four  levels  of  expansion,  two 
levels  which  are  to  be  merged  may  simply  share  the  same  definition.  The  object  is  to 
eliminate  the  need  for  editing  the  original  document.  The  output  format  is  determined  by 
the  library  of  macro  and  function  definitions  supplied  to  the  text  formatter  at  the  time  the 
document  is  processed. 

3.     FILE  DOCUIIENTATION  IN  SURVEY  RESEARCH 

A  significant  portion  of  the  Bureau  of  Social  Science  ResearcVi's  work  is  in  survey 
research.  The  basis  of  a  data  file  is  usually  a'  questionnaire.  The  questionnaire  is 
developed  by  the  principal  investigator,  who  usually  seeks  help  from  the  field  staff  and  tVie 
coding  staff  in  developing  question  formats,  coding  schemes  for  responses,  and  the  skip 
patterns.  Prior  to  the  development  of  the  system  described  here,  the  questionnaire  was 
typed  by  hand  or  produced  on  a  word  processing  system.  Host  questionnaires  are  designed  for 
keying  from  the  original  instrument,  rather  than  for  transcription  to  coding  sheets.  In 
some  cases,  open-ended  responses  must  be  converted  to  numeric  code  before  keying,  but  in 
most  cases  record  position  numbers  and  missing  data  codes  (for  blank  responses)  are  printed 
in  the  right  margin  of  the  questionnaire.  In  most  cases,  the  questionnaire  went  through 
several  drafts  before  being  submitted  to  computing  services  for  the  assignment  of  record 
position  and  missing  data  information. 
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3.1.  Data  dictionaries 

BSSR  processes  most  of  its  survey  data  files  V7ith  OSIRIS  IV,  a  hierarchical  data 
management  and  statistical  system  developed  at  the  University  of  Michigan.  OSIRIS  IV,  like 
all  modern  data  management  systems,  requires  that  data  be  defined  by  a  machine-readable 
dictionary.  Usually,  the  writing  of  a  dictionary  description  v;as  deferred  until  the 
questionnaire  had  been  sent  to  the  printer.  A  computing  specialist  used  a  paper  copy  of  the 
questionnaire  as  a  guide  for  keying  a  file  giving  each  data  items  identifier,  name, 
location,  v/idth,  T.iissing  data  indicators,  etc. 

3.2.  Editor's  codebook 

"  llaiiy  questionnaires  contain  open-ended  items  which  are  coded  after  the  interviev;,  but 
prior  to  keying.  A  question  such  as  "Uow  do  you  spend  your  spare  time?"  may  have  more  than 
one  answer  and  may  include  responses  whicVi  are  entirely  unforeseen  at  the  time  the 
questionnaire  v;as  designed.  In  such  cases,  a  set  of  blank  lines  is  printed  on  the 
questionnaire  and  eight  to  ten  columns  allocated  in  the  record.  The  expectation  is  that 
there  will  be  no  more  than  95  categories  of  answer  and  that  no  one  V7ill  mention  more  than 
four  or  five  activities.  The  actual  allocation  of  the  columns  into  variables  is  done  after 
the  coding  scheme  has  been  establislied .  The  occasional  occurrence  of  responses  requiring 
more  than  the  allocated  space  results  in  some  extra  v7ork  to  add  one  or  more  data  items  to 
the  end  of  the  file.  Usually,  the  editing  codebook  v/as  constructed  by  cutting  and  pasting  a 
questionnaire  into  a  question-per-page  format. 

3.3.  Analysis  and  codebook 

Once  the  file  has  been  cleaned  and  scales  and  indices  constructed,  it  is  passed  to  the 
analyst.  The  analyst  usually  uses  an  abbreviated  codebook  containing  only  the  variable 
identifiers,  labels,  and  category  values  and  labels.  The  statistical  system  produces  a 
formatted  version  of  the  machine-readaole  dictionary  vjhich  is  most  often  used  as  the 
analyst's  codebook. 

3.4.  Archival  user's  guide 

An  increasing  number  of  statistical  files  are  converted  to  an  archival  or  public  use 
form.  Such  archival  files  require  a  summary  form  of  documentation  whicVi  will  relieve 
secondary  users  of  the  necessity  of  consulting  a  file's  primary  users.  An  archival  user's 
guide  usually  contains  an  account  of  the  project's  adjectives  and  history,  a  history  of  data 
collection  and  file  processing  activities,  and  a  codebook  for  the  machine-readable  data 
file. 

Tlie  archival  codebook  contains  the  complete  text  of  questions  and  values,  labels,  and 
explanatory  text  for  categories.  Vilien  possible,  an  archival  codebook  also  contains 
frequency  accounts  for  each  category  of  a  discrete  variable  and  means,  variances  and  ranges 
for  continuous  variables.  A  variety  of  systems  has  been  used  for  the  production  of  archival 
user's  guides.  In  some  cases,  tlie  machine-readable  dictionary  can  be  augmented  with 
additional  text  to  produce  such  a  document.  However,  in  most  cases,  user's  guides  are 
produced  de  novo  with  typewriters  or  word  processing  systems. 

4.     THE  BSSR  INTEGRATED  DOCUIIEIITATION  SYSTEM 

The  integrated  documentation  system  began  as  a  set  of  macro  definitions  and  functions 
for  the  formatting  of  questionnaires.  A  limited  set  of  syntactic  forms  was  devised  and  a 
set  of  Format  macros  was  developed  to  produce  those  forms.  Formats  counting  functions,  as 
v/ell  as  some  especially  written  functions  were  used  so  that  all  seriation  is  done  by  the 
document  processor.  Thus,  question  numbers,  category  values,  and  record  locations  are  all 
supplied  by  the  document  processor.  Questions  may  be  inserted,  deleted,  or  moved  about  at 
will  while  maintaining  complete  integrity  of  seriation. 
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Figure  1  shows  a  fragment  of  a  questionnaire  manuscript;  Figure  2  shows  the  fragment  as 
formatted  by  the  document  processor.  All  seriation  has  been  produced  by  Format.  Tlie 
thirteenth  use  of  the  "|q"  macro  has  produced  question  13  in  the  questionnaire.  The 
categories  have  been  numbered  serially  from  1.  The  "|col"  function  indicates  that  one 
column  is  to  be  allocated  for  the  result  and  that  a  missing  value  is  to  be  entered  as  "9". 
Since  question  numbers  are  not  known  until  execution  time,  questions  referred  to  in  the  text 
are  given  labels,  which  the  formatter  resolves  to  question  numbers.  In  this  case,  the 
question  is  labelled  "A9"  and  has  skips  to  questions  "A14",  "A37",  and  "C31".  In  the 
printed  questionnaire,  all  labels  have  been  resolved  to  question  numbers. 

|q(A9)  On  most  political  matters,  do  you  consider  yourself: 

IcskipCLiberal'  ,A14) 

I cskipC 'Moderate ' ,A37 ) 

I ccont( ' Conservative '  ,C3I )  |col(l,9) 

Figure   1:   A  questionnaire  manuscript  fragment. 

13.     On  most  political  matters,  do  you  consider 
yourself: 

Liberal  (SKIP  TO  Q.   21)   1 

Moderate  (SKIP  TO  Q.  28)   2 

Conservative  (CONTIIIUE  WITH  Q.   14)   3  18/9 

Figure  2:   Symbolic  labels  resolved  and  manuscript  formatted. 

4.1.     Data  dictionary  description 

The  questionnaire  formatter  contains  much  of  the  information  needed  for  defining  an 
entry  in  the  data  dictionary,  e.g.,  location,  width,  and  missing  data  code.  The 
questionnaire  manuscript  was  augmented  v;ith  a  number  of  functions  needed  for  the  production 
of  dictionary  information.  Figure  3  shows  the  fragment  from  figure  2  augmented  with  a  short 
variable  name,  a  second  missing  data  code,  a  file  identifier,  and  a  reference  number. 

|dict('Liberal  or  conservative')   |dmd2(4)   |did(CDS)   | drefno( 1014) 

|q(A9)  On  most  political  matters,  do  you  consider  yourself: 

IcCLiberal' ,  ,A14) 

|c('Moderate' , ,A37) 

I c( 'Conservative ',,,C31)  |col(l,9) 

Figure  3:   Questionnaire  manuscript  augmented  v;ith  dictionary  information. 

Figure  4  shows  a  line  of  the  set-up  for  the  OSIRIS  data  definition  program.  This  setup 
is  used  to  define  the  field  in  the  data  record  which  will  hold  the  information  from  question 
13.  The  output  from  the  dictionary  definition  program  is  a  machine-readable  data  dictionary 
for  the  questionnaire  data  file.  The  dictionary  allows  OSIRIS  IV  and  other  statistical 
systems  to  read  the  data  file,  take  appropriate  action  to  cope  vjith  missing  data,  and  label 
the  output  of  analysis  programs. 

VAR=14  NAME='Liberal  or  conservative'  C0L=18  WIDTI1=1  REF1IO=1014  - 
MD1=9  MD2=4  IU='CBS'  L=' 1 =Liberal , 2=Moderate , 3=Conserva ' 

Figure  4:  OSIRIS  IV  dictionary  description  record 
generated  from  the  manuscript  fragment. 
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The  dictionary  information  not  explicitly  supplied  in  the  manuscript  defaults  to 
commonly  used  values.  The  variable  number  is  incremented  by  one  for  each  succeeding  line  of 
variable  identification.  All  defaults  can,  of  course,  be  overridden  by  explicit  entries  in 
the  manuscript.  Figure  5  shows  the  same  fragment  formatted  as  part  of  an  archival  user's 
guide. [1]  The  statistical  system  was  used  to  generate  a  file  of  frequencies  v;hich  is  merged 
with  the  codebook  to  produce  the  printed  frequencies  to  the  left  of  the  category  labels. 


V14  Reference:  1014 

Liberal  or  conservative  File  I.D.:  CBS 

Location:   IC  Width:   1  Numeric  character 

Hissing  Data:   EQ  9  OR  GE  4 

On  most  political  matters,  do  you  consider  yourself: 

405  1  Liberal 

437  2  Moderate 

331  3  Conservative 

42  4  Hissing  data 

Figure  5:  Manuscript  expanded  into  user's  guide. 

4.2.     Further  extensions 

We  plan  to  produce  a  macro  library  which  will  format  the  manuscript  for  input  to  an 
information  retrieval  system.  system.  For  this  extension,  the  manuscript  would  be 
augmented  with  a  "|keyword"  function  with  retrieval  keywords  as  arguments.  The  function 
would  be  ignored  in  the  formatting  of  the  questionnaire  and  would  be  printed  in  the  usual 
keyword  format  for  the  user's  guide.  The  keyword  function  would  be  appropriately  redefined 
to  provide  proper  input  to  the  information  retrieval  system. 

5.     COST  AND  SCIIEDULItlG  BENEFITS 

The  original  purpose  of  the  documentation  system  was  to  save  time  and  effort  in  the 
preparation  of  questionnaires.  Satisfactory  results  were  obtained  in  the  first  use  of  the 
system,  when  multiple  versions  of  a  325-question  instrument  were  prepared.  The  original 
version  of  the  questionnaire  required  six  weeks  for  preparation,  (including  time  for 
debugging  of  the  formatting  system).  Preparation  time  for  successive  versions  went  from  one 
day  to  four  hours. 

An  unforeseen  effect  of  the  system  was  to  relieve  the  data  processing  section  of  some 
of  its  time  pressure.  Usually,  slack  in  the  schedule  is  consumed  during  the  earlier  phases 
of  the  project,  with  most  of  the  extreme  rush  occurring  during  computing,  analysis,  and 
writing.  As  the  system  developed,  it  became  clear  that  the  use  of  an  integrated 
documentation  system  was  improving  the  vjork  flow  throughout  the  questionnaire  and  file 
construction  process.  Variable  and  category  labels,  as  well  as  dictionary  information, 
could  be  inserted  at  the  tine  the  questions  were  drafted,  thus  moving  dictionary  definition 
work  several  months  forward.  The  use  of  an  integrated  system  also  made  questionnaire 
authors  aware  of  problems  which  might  arise  during  file  definition  and  construction.  The 
system  yields  savings  in  time  and  labor,  production  of  better  questionnaires  and  files,  and 
a  beneficial  redistribution  of  the  work  sequence. 
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6.     IMPLICATIONS  FOR  STAIIDARUIZATION 

The  work  described  here  has  implications  for  three  kinds  of  standardization.  that  of 
content,  output  format,  and  input  format. 

6.1.  Standardization  of  content 

Standardization  of  content  is  the  most  difficult  of  problems,  because  it  must  be 
applied  anew  to  each  new  work.  To  require  a  "complete  and  concise  abstract"  is  only  to  hope 
that  the  author  will  v;rite  such  an  abstract  this  time,  just  as  last  time.  Some  items  of 
content  are  constrained  by  technical  factors.  Codebooks  produced  by  the  system  described 
here  may  not  include  variable  names,  but  all  will  have  field  locations  and  widths,  for 
without  such  items,  the  system  cannot  produce  even  an  empty  codebook.  It  is  possible  to 
attempt  the  enforcement  of  content  standards  by  technical  means.  A  documentation  system 
might  forbid  the  use  of  strings  of  blanks  as  variable  names,  or  might  require  that  an 
abstract  contain  at  least  240  non-blank  characters.  (The  reader's  speculations  as  to  the 
efficacy  of  such  restrictions  are  as  least  as  good  as  mine.)  lly  feeling  is  that 
standardization  of  content  can  be  enforced  within  a  contractual  relation,  but  not 
necessarily  within  a  community. 

6.2.  Standardization  of  output  format 

Since  the  output  format  is  entirely  imposed  by  the  documentation  system,  the  format  of 
all  automated  documentation  is,  ipso  facto,  standardized.  Tlie  problem  of  standardizing  an 
output  format  thus  reduces  to  one  of  convincing  those  vjith  responsibility  for  documentation 
systems  to  support  a  standard  format.  Once  written  into  a  documentation  system,  tVie 
standard  format  is  automatically  imposed  on  the  authors  of  documentation. 

6.3.  Standardization  of  input 

Ttie  input  and  output  of  a  documentation  system  are  equivalent  in  content,  but  differ 
greatly  in  form.  The  question  therefore  arises  as  to  whether  a  standard  format  should  be 
imposed  on  the  input  to  documentation  systems,  lly  feeling  is  that  such  standardization 
efforts  would  be  unduly  restrictive  and  would  be  ignored.  Text  processing  languages  are 
being  developed  at  a  great  rate.  People  are  developing  new  text  processing  procedures  and 
languages,  v/hich  they  will  promulgate  with  a  fine  disregard  for  standards  and  restrictions. 
The  time  for  standardization  of  text  processing  languages  has  not  yet  arrived. 

The  lack  of  a  standard  for  text  processing  languages  is  ameliorated  by  the  relative 
ease  with  which  a  manuscript  file  in  one  language  can  be  translated  to  another  language. 
Since  all  formatting  information  is  in  a  regular  form,  there  is  usually  little  difficulty  in 
writing  a  procedure  which  will  do  much  of  the  translation  work.  Translation  beyond  the 
power  of  a  straight  forward  program  usually  involve  differences  in  the  capabilities  of  the 
source  and  target  documentation  systems.  Tlie  resolution  of  such  differences  usually 
involves  a  considerable  editorial  toucn. 
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Compilation  of  Bibliographic 
Data  Element  Dictionaries 

Madeline  M.  Henderson 

Consultant,   Bethesda,  Md. 

Under  sponsorship  of  the  National  Technical  Information  Service  (NTIS), 
a  project  has  been  started  to  compile  a  data  element  dictionary  (DED)  encom- 
passing all  the  bibliographic  data  elements  used  in  the  processing  of  Fed- 
eral documents.     These  elements  include  those  used  in  the  abstracting- 
indexing  type  of  processing  done  by  the  four  major  reports-processing  agen- 
cies  (NTIS,  Department  of  Defense,  Department  of  Energy,  and  National  Aero- 
nautics and  Space  Administration),   plus  those  used  in  the  library-type  of 
cataloging  done  by  the  Government  Printing  Office,  with  the  Library  of  Con- 
gress, based  on  the  family  of  MARC  formats.     The  purpose  of  such  a  DED  is 
two-fold:     first,   to  provide  to  the  reports-processing  agencies  a  too],  to 
guide  their  consideration  of  possible  further  standardization  to  achieve 
greater  compatibilities  and  improved  cooperative  processing  among  themselves; 
and  secondly,   to  provide  to  them  and  their  library  counterparts  a  mechanism 
by  which  to  explore  productive  avenues  of  cooperation  and  interfacing.  This 
DED  is  one  of  several  similar  efforts  now  underway  or  recently  completed; 
the  formats  used  and  the  experiences  gained  should  be  usable  by  other  efforts, 
perhaps  through  preparation  of  guidelines. 

Keywords:     Bibliographic  data;  Data  element  dictionary;  Guidelines. 

1.  INTRODUCTION 

The  data  element  dictionary,  as  defined  in  this  paper,   is  a  compilation  of  descriptions 
as  to  the  meaning,   contents,   and  rules  for  use  of  the  units  (elements)  specific  to  a  par- 
ticular data  base.     The  dictionary  catalogs  and  defines  the  data  elements;   it  does  not  lo- 
cate the  data  within  the  organization's  computer  system  nor  process  information  about  data 
entities  and  associated  data  processing  functions.     In  this  paper,   the  data  element  diction- 
ary is  a  more  narrowly-defined  management  tool  than  the  data  dictionary  system  for  which  the 
Institute  for  Computer  Sciences  and  Technology  has  proposed  guidelines   [1]  and  a  standard 
[2].     However,   the  dictionary  can  serve  as  one  step  in  the  process  of  improving  data  manage- 
ment and  therefore  deserves  consideration  for  preparation  of  user  guidelines. 

1.1    Purpose  of  Current  Project 

At  the  present  time,   four  Federal  agencies  —  the  Department  of  Defense's  Technical  In- 
formation Center  (DTIC) ,   the  National  Aeronautics  and  Space  Administration's  Scientific  and 
Technical  Information  Facility   (NASA/STIF),    the  Department  of  Energy's  Technical  Information 
Center  (DOE/TIC)  and  the  National  Technical  Information  Service  (NTIS)  —  perform  the  major 
tasks  in  the  bibliographic  processing  of  the  technical  reports  emanating  from  Federally- 
conducted  or  -sponsored  scientific  and  technical  research  and  development  activities.  The 
processing  involves  recording  the  pertinent  data  identifying  the  reports,  abstracting  and 
indexing  the  salient  information  contained  in  the  reports,  and  recording  the  means  by  which 
the  reports  can  be  obtained  from  one  or  more  of  the  above-mentioned  agencies. 

The  four  agencies  have  developed  computer-based  systems  to  process  the  reports  pertinent 
to  their  own  mission  responsibilities,   and  to  produce  various  forms  of  documentation  services 
based  on  them:     printed  abstract  bulletins  and  indexes,  machine-readable  data  bases,  special- 
ized alerting  services  and  bibliographies,  etc.     The  computer  services  are  unique  to  each 
agency  in  terms  of  specific  hardware  and  software,  but  the  exchange  of  bibliographic  infor- 
mation among  them  is  based  on  the  ANSI  Standard  Z39. 2-19  71  (updated  in  19  79)  format  for  bib- 
liographic information  interchange  on  magnetic  tape. 
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That  ANSI  standard  has  been  implemented  in  two  major  formats  —  that  employed  by  the 
reports-processing  agencies  identified  above  (the  COSATI  implementation)  and  that  used  by  li- 
braries in  sharing  cataloging  data  across  a  family  of  special  formats   (the  MARC  formats). 
These  two  systems  have  much  in  common  but  many  fundamental  differences  —  the  philosophy 
underlying  each  implementation  is  specific,  imbedded  in  its  own  community  of  users,  based  on 
years  of  practice,  and  well-nigh  immovable  against  change  or  casual  modification. 

Given  this  environment,  a  project  to  develop  a  data  element  dictionary  encompassing  both 
philosophies,  i.e.,  both  sets  of  data  elements,  seems  to  fly  in  the  face  of  prudent  activity. 
But  the  communities  agree  that  now  is  a  good  time  to  examine  and  evaluate  the  interfaces  be- 
tween these  two  philosophies/systems,  as  well  as  the  characteristics  of  the  systems  them- 
selves. 

Dating  back  to  19  78,  the  possibility  has  been  discussed  of  developing  a  data  element 
dictionary  (DED)  of  the  data  elements,  with  subsets  of  codes  and  rules,  used  by  the  reports- 
processing  agencies,  with  the  purpose  of  Investigating  needs  for  better  standards  and  proto- 
cols so  as  to  contribute  to  lowering  the  costs  and  increasing  the  speed  and  efficiency  of 
Federal  reports-processing  operations.     Present  procedures  of  the  four  agencies  need  to  be 
reviewed  with  a  view  to  determining  the  feasibility  of  formulating  a  network  concept  and  the 
impacts  and  benefits  of  such  a  concept  on  each  agency  and  the  user  community. 

More  recently,  the  possibilities  have  been  extended  to  include  the  data  elements  of  the 
library  community's  cataloging  operations.     Recent  developments  in  computer  processing  of 
bibliographic  data  have  included  cooperation  in  inputting  that  data  and  more  extensive  on- 
line access  to  the  resulting  files  of  data.     These  developments  have  been  particularly  suc- 
cessful in  the  library  community.     The  analysis  of  elements  in  a  DED  for  reports-processing 
should  be  undertaken,  it  is  felt,   in  light  of  the  successful  activities  underway  or  projected 
in  the  library  community,  in  order  to  improve  the  interfaces  and  interactions  between  these 
two  segments  of  the  total  information  processing  community. 

The  current  project,   then,  seeks  to  compile  a  DED  encompassing  all  the  data  elements 
used  in  the  processing  of  Federal  documents:     the  abstracting- indexing  operations  of  the 
four  agencies  plus  the  library-type  cataloging  done  by  the  Government  Printing  Office  (GPO) . 
The  purpose  of  such  a  DED  is  not  only  to  provide  the  four  agencies  a  tool  to  guide  their 
consideration  of  possible  improved  cooperative  processing  among  themselves,  but  also  to  pro- 
vide them  and  the  library  community  a  mechanism  by  which  to  explore  productive  avenues  of 
cooperation  and  interfacing. 

1.2     Relation  to  This  Meeting 

The  Institute  for  Computer  Sciences  and  Technology  (ICST)  has  initiated  discussions  of 
a  standard  for  data  dictionary  systems  (DDS),  defined  as  computer  software  "used  to  record, 
store,  and  process  information  about  an  organization's  significant  data  and  associated  data 
processing  functions."   [1]     A  fully  developed  data  dictionary  for  an  organization  is  defined 
in  ICST's  prospectus  for  a  standard  [2]  as  a  catalog  of  the  organizations'   data  resources 
but  also  "a  computer  data  base  that  fully  documents  its  data  collection,  processing,  hand- 
ling, and  dissemination  activities."    The  DED  efforts  described  here  do  not  constitute  as 
extensive  a  management  tool  as  the  DDS  of  concern  to  ICST;  however,   the  DED  can  benefit  from 
the  same  considerations  as  to  data  standardization  and  control. 

The  DED  can  help  the  agency  (or  agencies)  whose  data  are  described  to  "reduce  redundant 
data  collection  and  to  improve  the  utility  of  existing  data  resources."   [2]     The  DED  will 
highlight  similar  data  elements  and  suggest  actions  to  improve  effectiveness  and  reduce  costs 
in  redundant  data  gathering. 

Standardization  of  the  data  elements  unique  to  each  agency  and  of  those  used  across  all 
the  systems  can  improve  the  collection  and  sharing  of  data  among  agencies  and  systems,  par- 
ticularly between  the  two  types  of  systems  or  philosophies  as  described  earlier.     A  DED  can 
assist  efforts  to  develop  acceptable  standards  as  appropriate  to  the  overall  bibliographic 
processing  effort. 
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The  DED,  as  is  true  of  a  DDS,  can  assist  in  the  definition  of  new  systems  or,  even  more 
importantly,  during  the  upgrading  of  existing  systems.  The  DED  can  be  useful  in  determining 
the  effect  of  proposed  changes  in  the  total  operational  environment. 

From  these  factors,  it  is  apparent  that  a  DED  as  defined  here  is  an  important  component 
of  a  DDS  as  defined  in  ICST  documents.     As  such,  the  DED  will  benefit  from  efforts  to  define 
data  element  sources,  descriptions,  and  pertinent  rules  for  usage  within  the  bibliographic 
data  processing  communities,  leading  to  guidelines  for  a  tool  for  improved  management  of  com- 
puter files  and  data  bases  within  and  by  that  community. 

2,     CURRENT  DEVELOPMENT  EFFORTS 

In  the  process  of  defining  and  establishing  the  project  described  above,   to  compile  a 
dictionary  of  the  bibliographic  data  elements  used  in  the  processing  of  Federal  documents 
by  two  parallel  but  separate  processing  systems,  a  number  of  related  efforts  were  examined. 
Their  experiences  and  directions  were  valuable  in  guiding  the  design  and  initial  activities 
in  the  current  project. 

2.1  DTIC  Uniform  Data  System 

Of  particular  interest  was  the  data  element  dictionary  compiled  by  DTIC  in  its  develop- 
ment of  a  uniform  data  system.     As  noted  in  the  preface  to  the  published  dictionary,  DTIC 
currently  "maintains  four  separate  information  banks  that  operate  independently  of  each  other 
yet  contain  parallel  information."  [3]     The  DTIC  technical  report-processing  system  as  pre- 
sently operational  is  one  of  the  systems  to  be  included  in  the  NTIS  project.     DTIC's  objec- 
tive in  compiling  its  DED  is  to  provide  capability  of  standardized  access  to  all  like  data; 
for  this  purpose,  standardization  of  data  entry,  application,  and  retrieval  are  required. 
Such  standardization  and  the  restructuring  of  the  individual  data  bases  to  achieve  a  uniform 
system  makes  a  specific  data  element  required  in  one  data  base  available  for  use  in  another, 
if  appropriate. 

The  DTIC  data  element  dictionary  was  seen  as  an  authoritative  document  to  define  the 
elements  and  their  specific  uses,  to  serve  as  a  communication  link  between  system  designers 
and  users,  and  to  provide  an  effective  management  tool  for  DTIC's  information  systems. 

The  stated  purposes  of  this  dictionary  paralleled  those  of  the  NTIS-sponsored  project, 
at  least  in  part:     to  define  the  data  elements  used  in  several  information  banks  which  are 
independent  of  each  other  and  yet  basically  similar  in  purpose  and  content,  to  serve  as  a 
communication  link  among  those  responsible  for  the  individual  systems  and  those  who  use  them, 
and  to  provide  a  useful  tool  for  the  managers  of  the  individual  systems  in  reviewing  their 
unique  system  characteristics  and  for  their  collective  consideration  as  to  possible  stan- 
dardization and  community  activities. 

Of  course,  DTIC  started  out  with  the  avowed  intention  of  standardizing  across  the  sepa- 
rate systems  for  purposes  of  cost  effectiveness  and  efficiencies;  the  NTIS  project  offers 
only  the  means  to  consider  possible  standardization  for  purposes  of  further  cooperative 
activities  —  which  can  lead  to  improved  effectiveness  and  efficiency  as  a  long-range  goal. 

The  format  of  the  DTIC  dictionary  has  proved  useful  to  the  current  project,  as  has  its 
list  of  descriptive  units  for  each  data  element. 

2.2  UNESCO  Data  Element  Directory 

Another  pertinent  effort  is  the  UNESCO-sponsored  compilation  of  lists  of  data  elements 
in  six  formats  used  for  the  computer-based  exchange  of  bibliographic  data  between/among 
national  bibliographic  agencies.    [4]     The  purpose  of  the  document  is  to  provide  a  tool  to 
facilitate  analysis  to  determine  which  data  elements  in  the  various  formats  are  sufficiently 
similar  as  to  prove  hospitable  to  standardization  and  which  are  not  amenable  to  such  stan- 
dardization, either  because  recording  practices  differ  too  widely  or  because  an  element 
exists  in  one  format  and  not  in  another. 
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One  comment  in  the  introduction  to  the  document  is  particularly  pertiijent  to  all  similar 
data  element  compilation  efforts,   including  the  current  project:     "An  examination  of  this 
document  will  be  sufficient  to  assure  the  reader  that  the  analysis  of  existing  data  elements, 
and  the  arrival  at  a  single  set  of  elements  for  the  Common  Communication  Format,  will  not  be 
an  easy  task."    However,  the  first  steps  must  be  taken  and  the  analyses  attempted,  in  order 
to  accomplish  whatever  agreements  might  be  possible. 

Again,   the  format  of  this  DED  and  the  list  of  descriptors  about  each  data  element  were 
particularly  useful  in  the  design  of  the  current  project.     Experience  in  the  UNESCO  study  has 
proved,  for  example,  the  value  of  an  index  to  each  system's  list  and  an  overall  index  to  the 
compilation.     Originally  it  had  been  thought  that  providing  comparable  information  in  an  iden- 
tical format  would  be  sufficient  to  facilitate  comparison  and  analysis.     However,  variations 
in  terminology  make  it  difficult  to  know  where   (or  even  whether)   to  find  related  data  elements 
in  the  separate  lists. 

2.3  Archival  and  Manuscript  Records  Dictionary 

A  project  currently  underway,   sponsored  by  the  Society  of  American  Archivists,  involves 
the  compilation  of  a  dictionary  of  data  elements  for  more  than  20  archival  and  records  hold- 
ings systems.     The  list  of  information  about  data  elements  collected  includes  descriptors 
about  the  data  element  itself,  plus  descriptors  about  the  system  in  which  the  data  elements 
operate:     system  limits  as  to  number  of  characters  per  record,  for  example,  number  of  fields 
per  record,  length  of  field,  etc.     These  characteristics  were  needed,  it  is  said,  because 
the  purpose  of  the  data  element  dictionary  is  to  provide  means  not  only  for  standardizing 
the  data  elements  themselves  but  also  for  exchanging  data  among  the  systems. 

Most  of  the  participating  organizations  chose  to  report  about  their  data  elements  in 
machine-readable  form,  following  a  data  collection  form  developed  for  the  project.     The  data 
were  "recorded  in  a  simple  word  processing/file  management  system  on  an  in-house  mini  for 
report  generation  purposes,"  according  to  the  project  manager. 

This  project  represents  a  more  extensive  data  gathering  activity,  across  more  files, 
than  the  others  described  above;  however,  the  number  of  descriptors  about  the  data  elements 
is  similar  to  that  of  the  other  efforts. 

2.4  The  NTIS-Sponsored  Project 

The  purpose  of  the  project,  to  compile  a  data  element  dictionary  for  the  bibliographic 
data  used  in  processing  Federal  documents,  has  already  been  described.     The  effort  at  this 
time  involves  the  development  of  the  data  gathering  form  and  the  definition  of  machine  re- 
quirements as  to  format  and  recording  media.     The  computer  system  at  GPO  has  been  offered 
for  the  collection  of  descriptions  about  the  data  elements  and  for  the  generation  of  the 
total  compilation  and  accompanying  indexes,   as  well  as  specialized  sub-reports  such  as  nu- 
meric listings  of  tags  used,   for  example.     The  computer  system  at  DTIC  has  also  been  offered; 
at  this  time  details  on  specific  machine  requirements  are  being  compared  and  resolved. 

The  descriptors  to  be  recorded  about  each  data  element  in  each  system  represent  a  com- 
bination of  those  already  used  in  the  various  efforts  described  above.     More  descriptors 
about  the  elements  themselves  will  be  recorded  than  were  used  in  the  DTIC  and  UNESCO  ven- 
tures, but  fewer  items  about  the  computer  systems  will  be  captured  than  in  the  archives  pro- 
ject. 

The  current  project  differs  also  from  some  of  the  other  efforts  in  that  the  data  ele- 
ments will  be  identified,   defined,   and  recorded  by  each  of  the  participating  agencies  rather 
than  by  a  centralized  activity.     This  decision  is  based  on  the  feeling  that  the  need  to  so 
identify  data  elements  will  be  a  useful  exercise  for  the  system  managers.     The  DED  project 
at  Defense  has  already  been  described;  NASA/STIF  has  just  initiated  a  review  of  its  data 
entry  procedures,   so  the  DED  effort  will  complement  that  program  also. 
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3.     POSSIBILITY  FOR  GUIDELINES 


The  NTIS-sponsored  project  to  compile  a  data  element  dictionary  of   the  bibliographic 
data  elements  in  the  processing  of  Federal  documents  represents  one  example  of  a  number  of 
similar  efforts.     These  constitute  a  recognition  by  system  managers  of  the  value  of  compil- 
ing and  reviewing  a  system's  data  elements  in  a  structured  manner.     As  noted  by  ICST,  "agen- 
cies are  striving  to  reduce  redundant  data  collection,"  because  of  increasing  costs  of  labor- 
intensive  data  handling.     In  addition,  a  DED  can  support  the  development  of  data  standards, 
so  that  data  collected  for  one  purpose  can  serve  another  as  needed  by  various  activities. 

Review  of  the  current  project  and  the  related  efforts  described  above  can  lead  to 
guidelines  about  the  bibliographic  data  elements  which  should  be  described,  the  extent  of 
descriptions  about  each  element  which  will  yield  valuable  information  for  management  de- 
cisions, and  the  type  of  machine  processing  of  the  descriptions  which  will  produce  the  most 
effective  tools  to  aid  in  making  those  decisions. 

For  example,   the  guidelines  would  define  the  bibliographic  data  elements  which  should 
be  captured  for  any  individual  system  for  which  a  dictionary  is  to  be  compiled.  Further, 
the  guidelines  would  list  the  minimum  number  of  descriptive  items  which  should  be  recorded 
about  each  bibliographic  data  element  in  order  to  compile  a  dictionary  of  such  elements: 
name  of  the  element,  narrative  definition,  rules  for  use  of  the  element,  source  (i.e., 
system  in  which  it  is  used),  character  set  permissible,   tags/indicators  used  with  the 
element,   etc.     Some  nine  of  these  descriptive  items  have  been  defined  for  all  four  current 
efforts  described  above. 

The  guidelines  would  also  describe  the  steps  in  machine  processing  to  yield  the  most 
useful  dictionary:     designation  of  fields  to  be  used  in  preparing  indexes  to  the  dictionary 
listing,  which  items  are  best  input  in  fixed  length  fields  and  which  must  be  allowed 
variable  length  input,  and  the  format  found  most  useful  in  both  the  dictionary  entries  and 
the  indexes  to  the  dictionary. 

Development  of  guidelines  is  best  done  through  appropriate  standards-setting  bodies 

such  as  ANSI  Committee  Z-39  on  Library  and  Information  Sciences  and  Related  Publishing 

Practices.     If  such  guidelines  are  completed,  they  could  be  offered  simultaneously  as  FIPS 
Guidelines  for  Federal  use. 

It  needs  to  be  said  again  that  the  DED  is  a  step  in  the  process  of  improving  data 
management;   the  DED  can  guide  system  managers  about  internal  operations  and  cooperative 
activities  with  other  systems.     But  the  decisions  as  to  data  standards,   for  example,  are 
a  step  beyond  the  compilation  of  a  DED.     What  is  suggested  here  is  preparation  of  guidelines 
for  the  compilation  step  only. 

Further  standardization  procedures  will  not  be  easy  to  accomplish.     The  existing  sys- 
tems represent  a  major  investment  of  resources  in  hardware  and  software,   in  procedures  and 
processes,   in  products  and  services  that  exist  and  fulfill  the  mission-required  responsi- 
bilities of  the  agencies.     To  talk  of  changing  those  systems  to  meet  community- imposed 
standards  causes  grave  concern,  and  rightly  so,  on  the  part  of  the  system  managers.  As 
noted  in  the  ICST  documents,  the  utility  of  a  given  capability  for  a  sufficiently  important 
segment  of  the  community,   in  view  of  known  constraints,  must  be  determined  before  standardi- 
zation efforts  can  be  successfully  undertaken. 

This  becomes  especially  important  when  the  suggested  standardization  encompasses  two 
distinct  system  types  or  philosophies  about  the  bibliographic  processing  of  Federal 
documents.     There  is  a  tendency  to  fear  being  subsumed  or  "swallowed  up"  by  one  approach  or 
the  other.     This  fear  has  been  expressed,   in  particular,  about  the  abstracting- indexing  sys- 
tems of  the  four  reports-processing  agencies  because  of  the  more  pervasive  cataloging  sys- 
tem and  numerous  MARC-based  formats  used  by  the  library  community. 
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4.  CONCLUSIONS 


What  is  needed,  then,  to  sustain  the  momentum  toward  improved  efficiencies  and  effec- 
tive coordination  is  to  complete  the  compilation  of  the  dictionary  of  bibliographic  data 
elements  used  in  processing  Federal  documents.     That  effort  itself  will  help  the  individual 
system  managers  to  recognize  the  current  status  of  their  data  elements  and  may  suggest 
changes  or  modifications  for  the  individual  systems. 

The  compilation,  further,  will  point  up  similarities  and  differences  in  the  handling  of 
common  data  elements  and  may  suggest  areas  for  discussion  and  compromise  leading  toward  im- 
proved efficiencies  in  the  overall  procedures  for  bibliographic  processing.     One  projection 
calls  for  the  five  systems  to  try  to  reach  agreement  and  standardization  for  handling  a  set 
of  core  data  elements  common  to  all  systems,  so  that  initial  processing  of  Federal  documents 
can  serve  the  different  needs  of  the  individual  systems  for  specific  products  and  services. 
Thus  sharing  of  bibliographic  input  can  result  in  sharing  of  information  resources,  with 
accompanying  savings  and  improved  timeliness  for  users  of  the  systems. 
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of  bibliographic  citations  in  data  bases  and 
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Bibliographic  citations  taken  from  the  major  databases  cannot  be  used  in 
their  original  form  for  publication  in  most  American  journals  because  of 
editors'  capitalization  practices.     These  are  based  on  rules  invented  a 
long  time  ago  that  run  counter  to  normal  English  orthography  and  are  based 
merely  on  tradition.     They  have  no  justification  from  a  linguistic  point 
of  view,  and  may  even  make  titles  ambiguous.     The  relevant  American 
Standard  ANSI  Z39.29,  based  on  the  International  Standard  ISO  4,  allows 
two  different  styles  for  titles  of  monographs  or  serials,  but  only  one — 
normal  orthography — for  titles  of  articles  or  papers.     Most  major  data- 
bases also  use  normal  English  orthographic  rules  for  titles,  but  some 
render  titles  in  all  capitals,  a  practice  which  may  also  be  detrimental 
to  rapid  exchange  of  bibliographic  data  among  different  media.  While 
printers  may  display  titles  any  way  they  like,  journal  editors  and  data- 
base producers  should  adhere  to  the  commonly  accepted  orthographic  stand- 
ard (followed  also  by  the  Library  of  Congress) ,  namely  capitalization  of 
only  the  first  word  and  all  proper  names  or  acronyms  in  a  title.  This 
would  make  it  possible  to  transmit  bibliographic  data  for  references  or 
footnotes  directly  from  a  database  without  time-consuming  and  error-prone 
re-editing  for  capitalization. 

1.  INTRODUCTION 

The  generation  and  display  of  bibliographic  data  in  databases  as  well  as  in  conventional 
printed  publications  suffers  at  present  from  a  complete  lack  of  uniformity  which  is  due  to 
three  different  conditions  of  standardization; 

(a)  the  existence  of  a  multiplicity  of  standards  which  are  either  overlapping,  mutually 
contradictory,  or  applied  in  sometimes  quite  different  ways  by  the  producers  of  re- 
corded information; 

(b)  a  lack  of  standards,  resulting  in  idiosyncratic  rules  and  solutions  of  certain  prob- 
lems ;  and 

(c)  the  persistence  of  obsolete  quasi-standards ,  invented  by  unknown  people  on  their  own 
authority,  sometimes  in  a  distant  past,  when  they  were  geared  to  publication  methods 
and  patterns  that  have  now  themselves  become  entirely  obsolete. 

Condition  (a)  has  been  very  well  analyzed  and  summarized  in  two  papers  [1,  2]  which  unfort- 
unately appeared  in  rather  out-of-the-way  or  limited-distribution  publications,  but  deserve 
close  study  by  anybody  interested  in  international  standardization  of  bibliographic  data. 
Condition  (b)  will  be  discussed  at  and  perhaps  ameliorated  by  the  results  of  this  workshop. 
Here,  I  wish  to  address  only  one  seemingly  minor  or  even  trivial  aspect  of  condition  (c) , 
namely  the  capitalization  of  words  in  titles  of  monographs,  serials,  and  individual  artic- 
les   and  papers  (the  latter  forming  the  vast  majority  of  all  bibliographic  references  in 
data  bases) .     I  was  recently  made  aware  of  the  adverse  effects  of  quasi-standards  pertain- 
ing to  capitalization  when  I  had  to  write  a  review  article,  referring  to  a  large  number  of 
books  and  articles.     Many  of  the  references  came  from  searches  performed  on  several  data- 
bases, both  printed  and  electronically  accessible.     Most  titles  in  the  printed  sources  as 
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well  as  in  computer  printouts  were  displayed  in  normal  English  orthography,  i.e.  only  the 
first  word  and  proper  names  or  acronyms  were  capitalized.     References  found  4.n  library  cat- 
alogs, all  written  in  the  style  of  the  Library  of  Congress,  also  followed  the  same  pattern. 
But  when  the  manuscript  was  submitted  to  the  editor,  every  single  reference    had  to  be  re- 
worked manually  so  as  to  conform  to  arcane  rules  of  capitalization  followed  by  the  journal. 
This  was  a  boring,  tedious,  time-consuming,  and  entirely  meaningless  and  illogical  task.  I 
asked  myself:  is  this  not  a  terrible  waste  of  time  and  energy,  expended  only  to  satisfy  the 
whims  of  people  now  long  since  dead  and  forgotten  who  dreamed  up  rules  of  capitalization  in 
the  horse-and-buggy  age?     Is  it  really  necessary  or  useful  to  do  this  now  that  bibliograph- 
ic data  can  be  generated  at  one  focal  point,  transmitted  electronically  to  one  or  more  data- 
bases, displayed  at  will  in  any  desired  configuration  on  CRT  screens,  transformed  into  print- 
outs and  retransmitted,  perhaps  using  one's  own  home  computer  linked  by  telephone  lines  to  a 
receiving  word  processor  or  similar  device  in  the  editorial  office  of  a  journal? 

2.  PRESENT  RULES  OF  CAPITALIZATION 

To  answer  this  question  objectively,  it  is  necessary  to  examine  the  rules  on  which  present 
American  editorial  practices  are  based.     Most  American  editors  follow  the  rules  of  the 
Manual  of  style  of  the  University  of  Chicago  Press,  the  latest  edition  of  which  appeared  in 
1969  [3].     This  code  of  practice  essentially  preserves  rules  of  orthography  and  in  particul- 
ar those  of  capitalization  that  can  be  traced  to  the  early  days  of  the  century  and  perhaps 
even  further  back  in  time.     The  relevant  rule,  7.123  Cap-italization ,  stipulates: 

Capitalize  the  first  and  last  words  and  all  nouns,  pronouns,  adjectives,  verbs,  adverbs, 
and  subordinate  conjunctions.     Lowercase  articles,  coordinate  conjunctions,  and  preposi~ 
tions,  regardless  of  length,  unless  they  are  the  first  or  last  words  of  the  title  or  sub- 
title.    Lowercase  the  to  in  infinitives. 

The  anonymous  authors  of  this  edict  do  not  tell  us  (a)  why  any  words  other  than  first  ones 
and  proper  names  must  be  capitalized,  just  because  they  happen  to  be  title  words,  contrary 
to  normal  English  spelling  rules;  and  (b)  why  articles,  coordinate  conjunctions  and  preposi- 
tions are  being  demoted  to  second-rate  status,  as  it  were.  Indeed,  nobody,  not  even  the 
editors  of  the  Manual,  seems  to  know  the  answer,  because  in  every  American  style  book  (and 
their  number  is  legion)  the  same  or  similar  rules  are  stated,  but  they  are  never  justified 
as  to  the  specific  function  they  are  to  fulfill.  It  is  just  that  the  rule  is  on  the  books 
"because  we  have  always  been  doing  it  this  way". 

As  an  aside,  it  should  be  noted  that  the  dichotomy  between  coordinate  and  subordinate  con- 
junctions by  no  means  exhausts  the  several  categories  of  conjunctions  distinguished  by  tra- 
ditional grammarians,  such  as  copulative  (which  seems  to  be  only  a  fancier  version  of  coor- 
dinate, the  standard  example  being  the  word  and),  correlative  (.neither^  nor),  adversative 
(but,  however),  illative  {therefore,  thus),  and  temporal  {when),  all  of  which  are  expected 
to  be  known  and  duly  capitalized  or  not,  as  the  case  may  be,  by  writers,  editors,  typeset- 
ters and  proofreaders.     The  fact  of  the  matter  is  that  the  classification  of  words  in  trad- 
itional grammars  goes  back  to  the  eight  classes  of  words  listed  in  the  Teohne  grarrmatike ,  a 
Greek  grammar  written  by  Dionysius  Thrax  (1st  c.  B.C.)  whose  authority  was  never  challenged 
until  the  advent  of  modern  linguistics.     There  are  no  such  rigid  classifications  of  words, 
neither  for  Classical  Greek  nor  for  modern  languages,  much  less  are  there  "unimportant" 
words,  because  just  the  so-called  "function  words"  (among  which  are  the  poor  conjunctions 
and  prepositions)  are  those  parts  of  speech  that  make  meaningful  communication  possible, 
especially  in  English  which  has  shed  almost  all  of  its  inflectional  devices,  and  relies  in- 
stead on  syntactical  position  of  words. 

The  author  of  the  well-known  Manual  for  Writers  of  term  papers,  theses  and  dissertations  [4] 
Kate  L.  Turabian,  also  of  the  University  of  Chicago  Press,  follows  the  same  rules  but  adds 
some  intriguing  and  even  more  arcane  provisions,  no  doubt  to  enhance  the  "scholarly"  flavor 
of  term  papers  and  theses,  the  contents  of  which  often  fall  woefully  short  of  being  either 
scholarly  or  scientific.     In  her  rule  4:5  we  are  told  that  in  "scientific  fields",  capital- 
ization of  title  words  should  be  "kept  to  a  minimum"  (no  reason  given) ,  but  in  the  humani- 
ties and  in  "most  of  the  social  sciences"  (no  indication  which  of  these  do  or  do  not  quali- 
fy) the  "rules  given  in  the  following  paragraphs"  are  to  be  followed;  those  rules  are  a  more 
elaborate  recapitulization  of  those  in  the  Manual  of  style.     In  the  chapter  on  "Scientific 
papers",  rule  12:9  shows  two  examples  of  citatiors  in  which  title  words  are  not  capitalized. 
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That  would  seem  to  be  in  accordance  with  what  was  stated  earlier  in  rule  4:5.     However,  in 
rule  12:17  we  are  told  that  the  style  of  some  additional  examples  follow  that  of  "the  lead- 
ing publications  in  the  several  fields"  (again,  without  naming  them;  only  the  author  knows 
what,  in  her  infallible  opinion,  are  "leading  publications",  others  need  not  know — they  only 
have  to  accept  meekly  Turabian's  pontifical  dogma).     The  "fields"  are  exemplified  by  citat- 
ions of  works  pertaining  to  anthropology,  physiology,  psychology,  chemistry,  mathematics, 
and  physics;  of  these,  it  seems,  chemistry  and  physics  are  not  quite  as  scientific  as  the 
others,  because  the  examples  from  these  two  fields  do  capitalize  book  titles,  whereas  the 
rest  do  not.     Turabian  does  not  tell  us  what  is  de  rigeur  in,  say,  astronomy,  geology,  bio- 
logy or  other  scientific  fields,  so  writers  of  theses  in  those  areas  are  left  to  fend  for 
themselves . 

The  only  American  Standard  that  addresses  the  question,  MSI  Z39. 29-1977,  Amerioan  National 
Standard  for  bibliographia  references  [5],  is  not  unambiguous.  For  titles  of  monographs  and 
serials  its  section  4.7.3  Capitalization  gives  the  option  of  either  capitalizing  the  first 
word  of  a  title  and  each  significant  word  thereafter  (without  specifying  what  is  "signifi- 
cant") ,  or  to  capitalize  only  the  first  word  and  proper  names;  for  "analytic-level  titles" 
(which  means  articles,  papers,  etc.)  however,  only  the  second  rule  is  to  be  followed.  All 
of  this  is  based  on  the  provisions  of  the  International  Standard  ISO  4-1972,  Doovmentation 
— International  code  for  the  abbreviation  of  titles  of  periodicals  [6]. 

Finally,  the  country's  central  cataloging  agency,  the  Library  of  Congress,  invariably  uses 
regular  English  spelling  for  titles  of  monographs  and  serials  in  its  catalogs,  a  practice 
automatically  followed  by  all  libraries  as  well  as  by  the  bibliographic  databases. 

Thus,  the  picture  of  chaos  in  the  rendering  of  titles  in  bibliographic  references  as  pract- 
iced in  the  United  States  is  complete.  Here,  it  must  be  mentioned  that  most  British  printers 
and  editors  long  since  abandoned  special  rules  for  capitalization  of  titles  which  appear 
both  as  headings  of  articles  and  in  references  and  footnotes  in  normal  spelling.  Needless 
to  say,  this  introduces  yet  another  element  of  diversity  into  the  practices  of  bibliographic 
citation. 

3.  DISPLAY  OF  TITLES  IN  DATABASES 

The  display  of  bibliographic  data  in  hard  copy  by  various  database  producers  also  follows 
different  paths.     Here,  we  encounter  another  dichotomy,  namely  the  display  of  titles  in 
normal  English  orthography,  i.e.  upper-  and  lowercase  letters,  as  opposed  to  display  in 
ALL  CAPITALS.     A  brief  check  of  some  of  the  major  databases  revealed  the  following  picture: 
Biological  Abstracts ^  Chemical  Abstracts ^  Index  Medians ^  Public  Affairs  Information  Service, 
and  all  H.W.  Wilson  indexes  (the  latter  available  only  in  printed  form)  present  titles  in 
normal  orthography;  Engineering  Index,  ERIC  Resources  in  Education,  and  all  ISI  services 
print  titles  in  ALL  CAPITALS.     Needless  to  say,  a  title  printed  in  the  latter  style  must  be 
entirely  restructured  before  it  becomes  acceptable  to  an  editor  of  a  journal,  regardless  of 
its  capitalization  practices.     For  this  reason  alone,  database  producers  should  abandon  the 
practice  of  printing  titles  in  ALL  CAPITALS.     Other  weighty  arguments  against  this  practice 
are  the  following;   (a)  research  into  legibility  has  shown  that  anything  written  in  ALL  CAPS 
is  more  difficult  and  time-consuming  to  read  than  text  in  upper-  and  lowercase  [7];   (b)  ti- 
tles often  contain  abbreviations  or  acronyms  which,  if  all  are  written  in  uppercase,  tend 
to  "disappear"  among  the  words  of  a  title  or  may  be  misread,  e.g.  IN  may  be  the  word  "in", 
the  symbol  for  Indium,  the  zip  code  for  Indiana,  or  the  abbreviation  of  inch^   (c)  the  mean- 
ing of  a  title  may  be  affected  by  obliterating  the  distinction  between  common  words  and 
proper  names,  e.g.   "The  restoration  of  old  Egyptian  mummies"  is  not  the  same  as  "The  restor- 
ation of  Old  Egyptian  mummies",  and  "Simple  basic  data  files"  does  not  mean  the  same  as 
"Simple  BASIC  data  files";   (d)  chemical  elements  cannot  be  properly  identified  by  their 
symbols,  e.g.  Co  is  not  the  same  as  CO;   (e)  diacritical  marks  used  in  the  writing  systems 
of  foreign  languages  cannot  be  shown  when  ALL  CAPS  is  being  used,  while  it  is  at  least  pos- 
sible (though  normally  neglected  by  American  printers)  to  provide  these  important  marks 
which  may  affect  the  meaning  of  a  word,  e.g.  the  German  Mohren  and  Mffhren  mean  Moors  and 
carrots,  respectively,  and  the  Swedish  f&r  and  far  mean  sheep  and  father.     Although  the  con- 
text will  often  make  it  clear  what  is  meant,  there  is  still  room  for  ambiguity  and  error. 

If  typographical  diversity  in  the  hard  copy  presentation  of  bibliographic  data  is  desired, 
the  names  of  authors  may  be  printed  in  ALL  CAPS  (as  is  already  the  practice  of  some  data- 
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bases  and  abstracting  and  indexing  services).     This  is  much  less  subject  to  possible  error 
and  misinterpretation  than  the  complete  capitalization  of  titles,  although  the  problem  of 
diacritical  marks  in  personal  names  and  acronyms  as  parts  of  corporate  names  still  remains. 
Thus, wholesale  capitalization  should  be  avoided  as  far  as  possible,  and  different  typefaces 
should  be  used  instead,  where  feasible. 

4.  CONCLUSION 

At  a  time  when  interchangeability  and  compatibility  of  bibliographic  data  are  more  important 
than  ever  because  of  the  ease  with  which  data  can  be  transmitted  electronically  from  an  ori- 
ginator to  various  different  storage  media,  and  from  any  point  on  the  globe  to  any  other 
point — do  we  really  have  to  submit  to  the  chaotic  conditions  outlined  here,  imposed  on  the 
community  of  authors  by  unknown  persons  who  arrogated  to  themselves  the  prerogative  to  dic- 
tate which  English  words,  when  appearing  in  a  title, should  or  should  not  be  "dignified"  by 
capitalization?     The  answer  is  clearly  "no". 

Of  course,  we  cannot  and  should  not  tell  printers  and  graphic  designers  how  to  display 
titles  of  articles  in  journals.     What  we  should  be  concerned  about  is  the  rendering  of  such 
titles  in  bibliographic  control  tools  such  as  bibliographies,  catalogs,  lists  of  references, 
footnotes,  and  any  other  secondary  recording  of  titles,  and  the  most  effective  way  of  trans- 
mitting and  exchanging  such  data,  once  they  have  been  captured  in  machine-readable  form, 
without  the  need  for  any  restructuring  of  their  orthographical  form, 

I  hope  that  I  have  shown  that,  far  from  being  minor  or  trivial,  the  graphic  rendering  of 
titles  in  database  output  versus  their  display  in  printed  form  (that  is,  in  journals,  bib- 
liographies and  lists  of  references)  is  indeed  a  problem.     In  the  past,  before  the  advent  of 
centralized  storage  of  bibliographic  data  in  databases,  this  may  have  been  merely  an  innocu- 
ous game  played  by  editors,  but  it  is  now  becoming  a  nuisance  and  an  obstacle  to  rapid  com- 
munication of  data.     Fortunately,  it  is  also  a  problem  that  is  amenable  to  an  easy  solution, 
not  requiring  allocation  of  funds  or  costly  changes  in  equipment.     It  just  needs  some  common 
sense,  a  readiness  to  cooperate  and  adherence  to  an  already  existing  and  accepted  standard. 
The  gnomes  of  Chicago  have  played  their  games  of  irrational  and  idiosyncratic  capitalization 
for  too  long.     The  time  has  come  to  terminate  such  games,  the  rules  of  which  rely  on  the 
nebulous  authority  of  "time-honored  practices".     Thus,  editors  should  follow  the  normal 
rules  of  English  orthography  which  are  the  commonly  accepted  standard  of  written  communicat- 
ion, following  the  example  of  most  of  their  colleagues  on  the  other  side  of  the  Atlantic,  as 
well  as  that  of  the  Library  of  Congress.     As  to  database  producers,  it  seems  that  none  or 
only  a  few  of  them  are  following  the  archaic  practices  of  editors,  although  they  do  have  at 
least  two  different  typographical  practices  for  hard  copy  printout.     They  should  also  adopt 
the  standard  of  normal  English  orthography  for  titles  presented  in  hard  copy,  to  make  such 
presentation  uniform,  standardized,  and  easily  legible. 
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Session  F:     Enhancing  Software  Sharing 


DISCUSSION 

Linda  Tepp,  Recorder 

Cataloging  Distribution  Service,  Library  of  Congress 
Washington,  D.C. 

The  speakers  were  joined  by  two  discussants,  Joel  Lipkin,  King  Research,  Inc.,  and 
Alan  Wenberg,  National  Technical  Information  Service.  Mr.  Lipkin  is  a  Senior  Research 
Associate  at  King  Research,  with  primary  responsibility  in  the  area  of  data  processing. 
Among  his  more  recent  activities  is  heading  the  team  working  on  the  logical  design  for 
the  Dept.  of  Energy's  data  resources  directory.  Mr.  Wenberg  is  a  staff  member  of  the 
Office  of  Data  Base  Services  at  NTIS,  where  his  group  is  responsible  for  identifying 
available  software,  accessioning  and  distributing  machine-readable  products,  providing 
technical  assistance  to  users,  and  operating  the  Federal  Software  Exchange  Center  for  the 
General  Services  Administration.  Linda  Tepp,  the  recorder  for  this  session,  is  a  library 
information  systems  research  analyst  in  the  Cataloging  Distribution  Service  of  the 
Library  of  Congress.  Formerly,  she  was  a  program  analyst  in  the  Copyright  Office  of  the 
Library. 

The  discussion  began  with  Ms.  Dodd's  paper  in  which  she  suggested  that  the  user 
header  labels  could  be  a  useful  option  to  implement.  Ms.  Maruyama  posed  the  question  as 
to  whether  this  would  be  a  practical  point  to  consider  and  whether  this  could  become  a 
FIPS  standard.  Mr.  Wenberg  said  that  as  far  as  he  was  concerned  personally,  user  header 
labels  would  be  very  useful.  Overcoming  user  resistance,  however,  would  be  the  biggest 
problem  because  in  distributing  software  and  data  files,  approximately  five  to  ten 
percent  of  users  ask  NTIS  to  avoid  labels. 

As  a  historical  footnote,  Mr.  Wellish  commented  that  the  first  books  produced  during 
the  forty  to  fifty  years  after  the  invention  of  printing  did  not  have  title  pages.  Such 
things  did  not  exist  because  manuscripts  did  not  have  title  pages.  It  took  quite  some 
time  before  the  printers  of  that  time  realized  that  it  might  be  useful  to  have  some  kind 
of  general  label  or  announcement  up  front  that  would  tell  readers,  first  the  author,  then 
the  title,  and  even  when  and  where  the  book  was  printed — information  that  was  normally 
relegated  to  the  end  of  a  manuscript  as  it  still  is  in  Japanese  books  today.  Since  data 
bases,  historically  speaking,  have  just  been  born  yesterday,  it  may  also  take  a  few 
decades  until  the  producers  of  data  bases  or  other  such  documentation  begin  to  understand 
that  the  people  who  invented  the  printed  book  came  up  with  some  clever  innovations, 
namely  title  pages.    Ultimately,  title  pages  in  data  bases  may  become  commonplace. 

An  attendee  from  the  Control  Data  Corporation  said  that  user  header  labels  sound 
like  a  very  good  idea  as  long  as  they  don't  interrupt  the  current  labeling  facility  and 
they're  carefully  implemented  so  that  they  don't  produce  any  more  resistance.  Since  Mr. 
Wenberg  has  already  mentioned  some  user  resistance  to  labeling  and  it  took  the  industry  a 
long  time  to  get  where  it  is  with  labeling,  he  would  prefer  having  what  we  have  now  rather 
than  winding  up  with  less. 

Mrs.  Butler  said  that  the  real  problem  with  labels  has  always  been  that  they  weren't 
easily  portable  from  one  type  of  hardware  to  another.  Also,  the  fact  that  seme  of  the 
files  are  binary  data  files  has  created  difficulties.  She  mentioned  another  issue  that 
came  up  when  standard  labels  were  being  debated.  ASCII  is  the  only  character  code  that 
has  a  standard,  so  the  user  header  label  has  to  be  an  ASCII  standard  label.  Many  data 
files  that  are  interchanged,  however,  are  not  in  ASCII  character  code. 

Ms.  Dodd  added  that  she  was  well  aware  of  the  problems  involved  in  using  this 
particular  option  and  the  resistance  on  the  part  of  computer  facilities,  but  somehow,  the 
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spirit  or  the  intent  has  to  be  manifested,  possibly  in  another  way.  She  raised  the 
question  as  to  whether  this  is  the  only  option  available  to  us  now,  and  because  it  is 
being  resisted  and  not  being  used,  what  could  be  an  alternative?  She  asked  if  there 
exists  some  other  kind  of  standard  or  labeling  device  or  title  page  equivalent  that  could 
be  incorporated  in  the  file  itself  because  it's  extremely  important  to  have  this  in  terms 
of  maintaining  some  kind  of  control  or  data  base  management.  Mr.  Wenberg  suggested  that 
one  possibility  might  be  to  create  a  small  file  in  front  of  the  actual  data  file  or 
program  file  that  is  being  interchanged.  It  would  be  a  separate  file  in  front  of  the  data 
file;  it  would  not  be  the  first  record  in  the  file.  Ms.  Dodd  said  that  such  a  proposal 
had  been  made  in  the  past  and  agreed  that  it  probably  deserves  more  attention. 

Mrs.  Butler  brought  up  another  point  that  a  distinction  should  be  made  between  tapes 
for  tape-resident  files  and  tapes  for  transmitting  data.  The  latter  is  merely  like 
mailing  a  parcel.  Most  people  who  are  using  the  data  files  are  not  using  them  from  tape 
but  from  another  resident  device.  She  also  expressed  a  need  for  something  inter- 
changeable besides  tape  pretty  soon. 

The  next  major  discussion  point  concerned  FIPS  30  (Software  Summary  for  Describing 
Computer  Programs  and  Automated  Data  Systems).  In  response  to  a  question  from  Ms. 
Maruyama,  three  attendees  (two  from  the  National  Technical  Information  Service  and  one 
from  Calculon  Corporation)  indicated  that  they  are  actively  using  FIPS  30. 

The  papers  presented  by  Ms.  Maruyama  and  Mrs.  Butler  addressed  the  need  to  revise 
FIPS  30  to  meet  changing  bibliographic  requirements  and  to  reflect  the  new  ANSI  X3.88 
standard  for  computer  program  abstracts.  Mr.  Lipkin  suggested  that  before  deciding  what 
should  be  included  in  FIPS  30,  a  question  should  be  asked  as  to  why  you  want  to  obtain 
someone  else's  software.  In  addition  to  putting  the  software  up  on  your  machine  or  using 
their  data  base  management  system,  there  may  be  some  other  things  that  you  would  want  to 
do  with  someone  else's  software,  which  might  necessitate  describing  attributes  that  had 
not  been  considered  up  to  this  point.  For  instance,  you  might  want  to  take  someone's 
module  and  look  at  it  in  terms  of  an  algorithm  and  implement  a  certain  capability.  You 
might  want  to  look  at  a  system  design  as  implemented.  Or,  you  might  want  to  copy  a  piece 
of  the  software  or  modify  an  existing  system.  These  factors  might  require  different 
kinds  of  material  as  part  of  the  software  documention.  Perhaps  we've  been  talking  mainly 
about  whole  systems,  such  as  transporting  a  circulation  system  or  a  data  base  management 
system,  but  the  possibility  for  sharing  individual  modules  does  exist  although  this  area 
has  not  been  addressed  at  any  great  length. 

In  answer  to  Ms.  Maruyama' s  question  as  to  whether  this  would  be  appropriate  for 
FIPS  30,  which  consists  of  the  program  abstract,  as  opposed  to  FIPS  38,  which  is  the 
software  documentation  itself,  Mr.  Lipkin  said  this  probably  relates  much  more  to  FIPS 
38.  ADA  as  a  language,  for  example,  provides  this  sort  of  capability  for  documenting 
packages — small  modules  which  could  be  considered  a  library  of  data  packages  that  could 
be  shared.  Mrs.  Butler  added  that  FIPS  30  does  include  the  capability  to  describe 
modules  as  well  as  entire  systems. 

The  next  discussion  point  considered  whether  a  standard  comparable  to  FIPS  30  should 
be  developed  for  machine-readable  data  files.  Ms.  Maruyama  mentioned  in  her  paper  that 
the  Office  of  Management  and  Budget  had  issued  a  directive  in  an  attempt  to  standardize 
some  of  the  elements  related  to  statistical  data  files.  Although  certain  agencies  are 
mandated  to  follow  this  directive,  it  doesn't  have  quite  the  same  clout  as  the  FIPS 
standards. 

Ms.  Dodd  said  that  the  directive  is  very  close  to  what  Mrs.  Butler  had  described  in 
her  paper  for  software.  The  elements  in  the  directive  start  with  the  bibliographic 
citation  for  the  data  file  and  then  go  into  identification  number,  summary,  geographic 
and  time  coverage,  technical  characteristics,  and  so  on.  The  standard  should  not  be 
limited  to  computer  software,  so  it  would  be  a  good  idea  to  extend  it  to  other  types  of 
files.    She  recommended  that  such  an  action  be  considered. 
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An  attendee  questioned  whether  the  Paperwork  Reduction  Act  doesn't  mandate  a  certain 
degree  of  this.  With  far  greater  usage  and  sharing  of  government  data,  how  will  the 
establishment  of  standards  be  affected.  Is  the  Act  already  affecting  standards?  Mrs. 
Henderson  mentioned  in  this  context  that  a  federal  information  locator  system  (FILS)  is 
being  established  which  is  supposed  to  be  a  file  of  descriptions  of  data  collections — not 
a  description  of  the  data  themselves  but  the  existence  of  a  data  collection.  She  hoped 
that  the  people  who  are  developing  FILS  are  adhering  to  FIPS  standards  if  they  apply. 

Mr.  Lipkin  said  that  one  of  the  preliminary  reports  on  FILS  was  devoted  to  the 
subject  of  their  own  data  element  element  dictionary  for  describing  government  data 
files,  so  he  surmised  that  they're  developing  their  own  data  element  dictionary.  In 
effect,  Mrs.  Henderson  continued,  they're  trying  to  compile  a  dictionary  of  all  data 
elements  found  in  all  of  the  files  so  that  one  would  be  able  to  find  a  particular  data 
element  in  certain  files  across  the  whole  government.  Mr.  Lipkin  also  mentioned  that 
FILS  was  not  limited  to  machine-readable  data  files  but  was  focused  mainly  on  government 
reporting  requirements.  A  related  project  attempts  to  do  the  same  thing  specifically  for 
machine-readable  data. 

The  last  discussion  topic  involved  Mrs.  Henderson's  paper  on  the  possibility  of 
developing  guidelines  or  standards  for  compiling  data  element  dictionaries  for  biblio- 
graphic information.  An  attendee  from  the  Dept.  of  Energy's  Technical  Information  Center 
said  that  the  discussion,  thus  far,  has  concentrated  on  data  elements,  standards  for  data 
elements,  and  incorporating  ANSI  X3.88  into  FIPS  30,  all  of  which  seem  to  be  applicable 
for  computer  software  and  perhaps  for  numeric  data.  He  asked  Mrs.  Henderson  if  she  was 
referring  to  a  data  element  dictionary  that  merges  bibliographic  data  and  software. 

In  response  to  this  question,  Mrs.  Henderson  said  that  in  talking  about  a  data 
element  dictionary,  she  attempted  to  relate  that  effort  to  data  directory  systems  (DDS)  , 
for  which  the  Institute  for  Computer  Sciences  and  Technology  has  generated  guidelines  and 
proposed  a  FIPS  standard.  One  of  her  former  colleagues  reminded  her  that  software 
documentation  or  program  documentation  is  a  different  problem  and  is  handled  by  a  differ- 
ent part  of  the  institute  from  systems  documentation  where  the  DDS  belongs.  She  still 
contended,  however,  that  enhancing  software  exchange  can  also  include  the  data  that  the 
software  carries.  As  such,  it  is  a  management  tool  that  is  part  of  management's  total 
arsenal  of  tools  to  improve,  maintain,  or  make  more  effective  its  computer-based  systems, 
particularly  for  bibliographic  data  processing. 

The  audience  may  have  been  misled  by  her  mentioning  the  study  of  interaction  among 
the  four  computer  systems  of  the  four  major  reports-processing  agencies  as  the  first  step 
toward  sharing  data.  The  data  element  dictionary  project  could  help  to  determine  what 
data  ought  to  be  shared. 

The  attendee  from  the  Dept.  of  Energy  said  that  his  interest  in  this  matter  stemmed 
from  his  attempts  to  move  NTIS  from  a  data  element  concept  for  bibliographic  data  to  a 
similar  approach  for  software.  In  this  context,  Mr.  Lipkin  reported  that  several  of  the 
data  dictionary  packages  available  now  allow  you  to  record  information  about  program 
modules,  or  systems,  as  well  as  about  files  and  record  interrelationships  among  numeric 
and  bibliographic  files,  and  the  software  processes.  Fran  his  perspective,  this  is  one 
of  the  really  important  advances  because  it  allows  you  to  maintain  documentation  in 
synchronization  with  maintenance  and  development  information  that  might  be  collected  in 
the  process  of  changing  a  module  and  updating  the  dictionary  record.  That's  one  method 
to  keep  your  documentation  current.  In  response  to  a  comment  that  there  might  be 
confusion  here  between  bibliographic  data  elements  and  software  data  elements,  Mr. 
Lipkin  said  that  although  they  are  different,  they  do  interact.  If  you  change  your 
files,  you  will  also  want  to  be  certain  that  the  programs  that  process  the  files  are 
recompiled.  The  integrated  dictionaries  provide  the  capability  to  monitor  the  fact  that 
you  have  recompiled  your  program  before  you  try  to  run  it  against  the  file.  It  forces  you 
to  good  practices. 

Mr.  Lipkin  also  summarized  the  project  that  he  is  presently  working  on,  which  is 
somewhat  related  to  the  FILS  project.    For  the  Energy  Information  Administration  (EIA)  of 
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the  Dept.  of  Energy,  a  data  resources  directory  is  being  developed  which  is,  initially, 
a  description  of  all  the  data  collection  systems  within  the  department — about  160 
systems.  The  forms  are  described  in  the  context  of  bibliographic  terms  and  data  collec- 
tion frames.  Data  elements  within  the  management  system  are  also  included,  and  enforce- 
ment for  any  modifications  is  handled  by  the  fact  that  the  same  system  is  used  by  EIA  to 
get  forms  approved  by  the  Office  of  Management  and  Budget  (0MB) .  In  other  words,  if  a  new 
form  is  desired,  that  information  is  input  into  the  system  and  output  as  a  report  for  0MB. 
The  system  also  allows  managers  to  find  out  what  information  they  could  collect  on  these 
forms.  The  system  is  being  expanded  to  machine-readable  data  files  and  to  publications 
in  an  attempt  to  create  a  linkage  between  the  two  "files"  and  to  include  descriptions  of 
major  software  packages  which  access  the  files.  What  is  being  attempted  is  to  develop  an 
environment  where  someone  can  manage  EIA  as  a  data  processing  system,  consisting  of  over 
160  systems,  over  100  publications,  and  thousands  and  thousands  of  machine- readable  data 
files. 
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Session  F:     Enhancing  Software  Sharing 


SUMMARY 

Lenore  S.  Maruyama,  Moderator 

Network  Development  Office,  Library  of  Congress 
Washington,  D.C. 

As  seen  from  the  Discussion  portion  of  this  session,  there  was  considerable  dialog 
among  all  the  participants  (speakers,  discussants,  audience)  on  the  papers  presented,  and 
it  is  hoped  that  the  exposure  to  the  different  aspects  of  software  sharing  has  stimulated 
thinking  in  this  area.  The  conclusions  listed  below,  however,  include  only  those  that 
might  lead  to  further  action  by  the  National  Bureau  of  Standards  in  the  near  future: 

•  Although  there  was  general  agreement  on  the  usefulness  of  a  user  header  label  to 
record  bibliographic  information  describing  a  machine-readable  data  file,  the  over- 
all discussion  indicated  that  there  may  be  too  many  difficulties  (some  perceived  but 
many  real)  to  overcome  that  might  prevent  its  acceptance  and  implementation.  One 
alternative  suggested  was  to  create  a  separate  (small)  file  in  front  of  the  data 
file  to  carry  this  information  instead  of  carrying  a  user  header  label. 

•  The  consensus  of  the  group  was  that  FTPS  30  (Software  Summary  for  Describing 
Computer  Programs  and  Automated  Data  Systems)  should  incorporate  the  new  elements 
from  the  American  National  Standard  for  Computer  Program  Abstracts  (ANSI  X3.88) . 

•  FIPS  30  should  be  expanded  to  cover  numeric  data  files,  or  a  new  FIPS  should  be 
compiled  to  handle  these  files.  This  work  should  be  based  on  the  directive  issued 
by  the  Office  of  Management  and  Budget  concerning  statistical  data  files. 
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SESSION  G:    Improving  Human  Interfaces 


Moderator:    Joseph  Psotka,  National  Institute  of  Education 


Users  of  software  documentation  face  many  practical  problems  that  can  be  overcome  by 
proper  design  of  the  human  interface.  This  session  will  deal  with  several  interface 
characteristics  designed  to  make  documentation  friendlier,  more  useful,  and  of  highe 
quality. 
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NBS  FIPS  Software  Documentation  Workshop,  March  3,  1982 


Designing  Software  Documentation  for  N on  -  tec h n i c a  1 

Users 


V.  Douglas  Mines 


House  Information  Systems 
U.   S.  House  of  Representatives 


FIPS  PUB  38  provides  guidelines  for  "automated  systems" 
documentation,  which  includes  "User  Manuals."  The  target 
audience  for  this  documentation  --  "non-ADP  professionals"  -- 
represents  an  increasing  proportion  of  software  users. 
Documentation  for  this  group  should  contain  the  basic 
information  described  in  FIPS  PUB  38,  and  should  meet  broad 
standards  of  clarity,  completeness,  accuracy,  and 
ease-of-use.  In  addition,  five  specific  design  techniques 
are  recommended:  (1)  emphasize  procedures  for  using  the 
software;  (2)  organize  documentation  by  system  function;  (3) 
provide  specific  and  complete  examples;  (4)  develop 
documentation  in  two  phases,  with  programmers  writing  initial 
version  to  be  modified  by  user  support  specialists;  and  (5) 
Incorporate  documentation  into  user  training. 

key  words:  automated  data  systems,  user  manuals 

1.  INTRODUCTION 


Historically,  software  documentation  has  been  written 
primarily  by  programmers  for  programmers.  It  has  involved 
one  programmer  telling  other  programmers  what  his  or  her 
software  did,  how  it  did  it,  and  why  it  did  it  that  way. 

With  the  widening  use  of  on-line  data  bases, 
electronic  messaging  (mail)  systems,  and  other  office 
automation  applications,  the  population  of  software  users  has 
broadened  to  include  many  individuals  who  are  not  full-time 
data  processing  professionals:  managers,  accountants, 
engineers,  office  workers,  and  a  host  of  other  professions. 
Each  year,  these  users  increase  in  number  and  become  a  more 
important  audience  for  software  documentation. 

Hence,   "user  manuals"  --  that  class  of  documentation  in 
which     programmers     talk,     not     to     other  programmers,  but  to 
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non-technical  software  users  --  become  progressively  more 
imporant  in  many  ADP  environments.  From  the  point  of  view  of 
the  software  developer,  this  documentation  is  a  key 
determinant  of  the  acceptance  and  usefulness  of  the  software. 

The  U.S.  House  of  Representatives  is  a  data  processing 
environment  in  which  software  documentation  for  non-technical 
users  is  particularly  important.  HOUSE  INFORMATION  SYSTEMS 
(H.I.S.),  the  computer  service  group  for  the  House,  supports 
9  on-line  data  bases,  2  scheduling  systems  that  require  data 
entry,  an  electronic  mail  system,  a  text  processing  system, 
and  a  variety  of  more  specialized  systems.  There  are  about 
3000  accesses  to  H.I.S.  computer  systems  distributed  to  users 
in  Washington  DC  and  across  the  country;  the  vast  majority  of 
these  users  are  not  data  processing  professionals. 

Under  these  conditions,  the  quality  of  user-oriented 
software  documentation  is  a  crucial  consideration,  and 
consequently  significant  attention  has  been  paid  to  its 
development.  This  paper  describes  a  set  of  simple  design 
principles  which  have  evolved  as  H.I.S.  has  attempted  to  meet 
the  challange  of  producing  high  quality  user-oriented 
documentation. 

2.   RECOMMENDATIONS  FOR  CONTENT 


Of  the  content  areas  for  User  Manuals  outlined  in  FIPS 
PUB  38,  "procedures  and  requirements"  is  of  greatest  interest 
to  non-technical  users.  Experience  has  shown  that  non-ADP 
professionals  have  only  passing  interest  in  "general 
information"  about  the  software  and  technical  characteristics 
of  the  "application."  Moreover,  when  dealing  with  a 
geographically  dispersed  user  population,  information  about 
performance  and  equipment  is  difficult  to  summarize  in  a  form 
that  will   hold  the  interest  of  non-programmers. 

2.1  RECOMMENDATION  ONE:  The  content  of  user  manuals  should 
emphasize  procedures  and  requirements. 

Our  first  design  principle  is  that  the  content  of  user 
manuals  should  focus  primarily  upon  procedures,  i.e.,  how  to 
use  the  software.  General  information  about  data  base 
structure  and  other  features  of  the  software  should  br 
provided.  However,  non-ADP  professionals  are  primarily 
interested  in  using  the  system,  and  the  bulk  of  the 
documentation  should  focus  upon  telling  them  how  to  do  so. 

3.   RECOMMENDATIONS  FOR  FORMAT 


There  is  general  agreement  that  all  software 
documentation  should  be  clearly  written,  easy  to  use, 
accurate,     and    complete.     As  most  of  us  are  painfully  aware. 
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much  of  it  isn't.  But  even  if  software  documentation  is 
clear  enough  to  meet  the  needs  of  programmers,  it  still  might 
not  meet  the  needs  of  non-programmers  who  are  not  accustomed 
to  working  with  computer  systems. 

Documentation  is  more  understandable  to 

non-programmers  when  the  software  is  described  as  the  user 
sees  it  --  as  a  set  of  functions  that  are  performed  in 
accordance  with  a  predetermined  set  of  system  commands.  The 
key  to  good  user  manuals,  then,  is  to  (1)  list  and  describe 
the  functions,  and  (2)  list  and  provide  examples  of  the 
commands  or  responses  that  cause  the  functions  to  be 
performed.  In  short,  the  documentation  describes  what  the 
software  does  and  how  it  does  it.  Hence,  our  second  and 
third  design  rules. 

3.1  RECOMMENDATION  TWO:  Documentation  should  be  organized  by 
function  as  understood  by  the  user. 

Software  documentation  is  usually  organized  in  terms  of 

commands      or      other     program    design     parameters;  this  is 

reflected     in     tables  of  contents  that  list  commands  and  page 

references,  without  telling  the  reader  what  the  commands 
accomplish  functionally. 

Instead,  it  is  recommended  that  documentation  be 
organized  by  function,  making  it  as  clear  as  possible  to  the 
user  what  the  system  can  do  and  the  commands  necessary  to  do 
it.  For  example,  in  systems  using  STAIRS  software  print 
specifications  are  set  under  the  browse  command.  It  is  more 
meaningful  to  have  a  section  in  the  documentation  entitled 
"setting  print  specifications"  than  to  have  one  entitled  "the 
browse  command."  Whenever  possible  section  headings  and  the 
table  of  contents  should  reflect  system  functions  that  the 
user  understands. 

Organizing  documentation  by  function  has  added  benefits 
in  environments  such  as  ours  where  a  non- techni cal  user  might 
work  with  five  or  six  different  software  packages.  It  turns 
out  that  the  basic  functions  of  on-line  data  bases  are 
surprisingly  consistent.  Users  sign-on.  select  data  base 
subsets,  set  output  formats,  perform  searches,  print  or  save 
queries,  then  change  data  base  subsets  or  sign-off.  There  is 
more  variety  across  text  and  word  processing  systems,  but  a 
small  number  of  generic  functions  can  be  identified  here  as 
well.  Users  create  a  document,  set  format  (tabs,  margins, 
page  length,  etc.),  enter  and  edit  text  (involving  cursor 
movement  and  edit  commands),  print  and  store  documents. 

When  user  manuals  are  organized  by  function,  there  is 
more  comparability  across  documentation  and  more  transfer  of 
learning  from  one  on-line  system  to  the  next  or  from  one  word 
processor  to  the  next.  This  makes  each  system  and  manual 
more  valuable. 
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3.2.  RECOMMENDATION  THREE:  Provide  at  least  one  specific 
example  of  each  system  function  or  command,  showing  both  the 
"user"  and  "system"  responses. 

FIPS  PUB  38  reflects  the  fact  that  "input  formats"  are 
the  key  element  of  the  procedures  and  requirments  of 
automated  data  systems.  In  on-line  data  bases  and  other 
interactive  systems,  software  usually  allows  for  a  system 
prompt,  to  be  followed  by  a  user  entry  (usually  a  command  or 
parameter),  followed  by  a  system  response  (usually  output 
data  answering  the  user  query).  Documentation  should  provide 
specific  examples  of  how  this  sequence  would  look  for  each 
major  system  feature. 

This  approach  makes  it  easy  to  provide  users  with  the 
information  discussed  in  PUB  38:  input  length,  sequence, 
vocabulary,  punctuation,  etc. 

4.     PROCEDURAL  RECOMMENDATIONS 


The  final  recommendations  concern  procedures  for 
creating  and  distributing  documentation. 

4.1  RECOMMENDATION  FOUR:  Develop  software  documentation  in 
two  phases. 

Documents  should  be  developed  in  two  phases.  First, 
the  applications  programmers  and  analysts  who  write  the 
software  create  a  technically-oriented,  detailed,  and 
complete  guide  to  the  software.  This  document  includes 
system  design  philosophy,  a  description  of  data  base 
structure  and  parameters  (if  applicable),  and  listings  of 
special   commands,  features,  default  options,  etc. 

In  the  second  phase,  user  support  personnel  (such  as 
training  specialists)  take  this  document  as  a  starting-point 
for  the  software  documentation  targeted  to  the  end-user. 
This  second- i tera ti on  produces  the  user  manual  that  is 
released  to  non-ADP  users.  H.I.S.  refers  to  these  as  "how-to 
manuals." 

4.2  RECCOMENDATION  FIVE:  Use  the  documentation  during 
training. 

Most  software  packages  designed  for  non- techni cal  users 
are  supported  with  training,  often  in  a  formal  classroom 
context.  Frequently,  software  documentation  is  handed  out  at 
the  end  of  these  sessions  or,  if  distributed  earlier,  is  not 
refered  to  during  training. 

A  better  approach  is  to  distribute  the  documentation  at 
the     beginning  of  training  and  use  it  as  the  basic  reference; 
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this  way,  users  learn  to  use  the  documentation  as  well  as  the 
system  itself.  In  other  words,  classes  teach  both  how  to  use 
the  software  and  how  to  use  the  documentation.  This 
seemingly  trivial  point  has  enormous  practical  implications 
for  increasing  the  sophistication  of  inexperienced  software 
users. 

5.  CONCLUSIONS 


At  one  point  in  the  evolution  of  data  processing, 
software  documentation  was  written  by  programmers  for 
programmers.  Today  many  large  installations  and  software 
vendors  who  create  software  used  by  non-programmers  are 
encountering  new  audiences  and  are  discovering  the  importance 
of  the  once  humble  user  manual.  This  paper  has  recommended 
ways  to  design  this  type  of  documentation  so  as  to  maximize 
its     contribution     to     the     success     of    a     software  package. 
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1.  Introduction 

Most  programs  and  their  supporting  documentation  pass 
through  many  stages  of  development,  use,  and  mainte- 
nance. These  software  documents  may  appear  offline 
on  paper  or  video.  They  may  also  appear  online 
displayed  on  a  paper  or  glass-faced  terminal.  These 
documents  communicate  their  contents  to  the  reader 
primarily  through  alphanumeric  symbols.  These  pages  or 
screens  of  information  must  effectively  communicate 
intentions,  states,  structures,  and  processes.  While 
good  conceptual  organization  and  verbal  editing  are 
crucial  to  effective  communication,  a  third  component, 
the  graphic  design  of  these  documents,  has  been 
neglected. 

Graphic  design  is  the  discipline  concerned  with  the 
communication  of  informational,  emotional,  and  aesthetic 
content  through  the  manipulation  of  typography,  sym- 
bolism, illustration,  color,  spatial  organization,  and  tem- 
poral sequencing.  [1]  Certain  professionals  in  this 
disipiine  are  concerned  primarily  with  the  communication 
of  complex  information  through  the  design  of  charts, 
maps,  diagrams,  and  other  technical  documents. 
Knowledge  from  these  professionals  and  their  literature 
can  be  applied  to  the  task  of  designing  the  graphic 
presentation  of  software  documentation  which  now 
faces  builders,  users,  and  managers  of  computer  sys- 
tems. Graphic  designers  usually  are  not  involved  in  set- 
ting up  conventions,  standards,  and  specifications  for 
producing  software  documentation.  In  order  to  educate 
the  information  specialists  and  computer  scientists  who 
normally  rely  upon  their  own  limited  expertise,  this  arti- 
cle focuses  on  the  typographic  principles  of  information 
oriented  book  or  document  design  drawn  from  the  pro- 
fessional literature  and  from  the  author's  own  experi- 
ence as  a  graphic  designer  of  computer-based  docu- 
ments [1  ;2;4]. 

The  software  documentation  interface  between  the 
human  being  and  machine  is  in  the  context  of  the  per- 
son using  a  computer  system  and  in  the  person  building 
or  maintaining  a  computer  system.  Elsewhere  the  author 
has  termed  these  the  inter-faces  and  the  inner-faces 
of  computer  systems.  [2]  Basic  principles  of  selecting 
visual  signs  and  their  attributes  (such  as  their  location, 
size,  and  boldness)  for  presentation  on  both  paper  and 
glass  can  enhance  the  legibility  of  software  documen- 
tation as  well  as  its  readability,  i.e.,  its  appeal  or 
friendliness. 

2.  Typographic  Aspects  of  Graphic  Design 

The  design  task  concerns  determining  a  relatively  high 
degree  of  fit  among  the  different  requirements  of  the 
components  of  every  communication  interface: 


Graphic  design  principles  have  been  utilized  in 
redesigning  the  interface  for  an  information  manage- 
ment system  and  for  prototypes  of  typographicly 
enhanced  textual  programs.  These  principles  are 
explained  and  examples  of  typical  formats  are  shown  to 
indicate  the  nature  of  improvements. 

the  sender  (the  machine  or  user) 
the  medium  (the  display  device) 
the  receiver  (the  user  or  machine) 
the  message  (the  information  content). 

By  means  of  the  position,  color,  size,  grouping,  and  tem- 
poral sequence  of  visual  signs  such  as  alphanumerics 
and  symbols,  the  graphic  designer  must  convey  the 
usual  facets  of  a  software  documentation  system:  con- 
tinuous prose  (e.g.,  help  messages  and  lengthy  expla- 
nations), interrupted  prose  (e.g.,  error  messages,  sys- 
tem status  reports,  examples),  and  tables  or  lists  (e.g., 
source  code,  menus,  data  dictionaries). 

Typographic  design  begins  with  a  concern  for  the 
design  of  individual  symbols.  In  many  current  display 
systems  there  is  relatively  little  control  over  symbol 
design.  A  limited  hardware  set  of  characters  is  often 
used  to  display  alphanumerics  and  other  symbols. 
Because  many  terminals  and  printers  currently  operate 
with  fixed-width  characters,  many  of  the  principles 
given  below  are  oriented  toward  this  situation. 

In  online  display,  there  is  often  little  control  over  symbol 
design;  it  is  likely  that  the  standard  medium  for  interac- 
tion may  be  a  display  showing  24  lines  of  80 
alphanumeric  characters  each.  The  use  of  reverse 
video,  italic,  or  levels  of  brightness  can  not  always  be 
assumed.  Even  if  these  means  of  visual  emphasis  are 
not  used,  other  approaches  are  available.  For  example, 
there  can  be  a  strong  reliance  on  a  horizontal  line  of 
hyphens  to  highlight  certain  titles  or  to  separate  divi- 
sions of  the  frame. 

Even  within  severe  limitations,  attention  to  graphic 
design  principles  can  improving  the  effectivenes  of 
software  documentation.  Consider  the  use  of  all  upper 
case  words,  a  typographic  approach  which  much  docu- 
mentation utilizes.  The  fixed  width  of  the  letters  are 
often  created  by  a  7x9  or  similar  dot  matrix.  In  such 
conditions  lower  case  letters  with  occasional  capitals 
are  more  legible.  Research  shows  [3,  35]  that  not  being 
able  to  perceive  word  shapes  (as  is  true  for  words  set 
in  upper  case  characters  only)  may  slow  reading  speed 
by  as  much  as  13%.  Because  line  printers  and  terminals 
often  have  little  space  between  lines  in  comparison  to 
normal  textbook  typography,  lower  case  letters  are 
particularly  important  in  providing  visual  space  between 
lines  of  type  and  thereby  improve  legibility.  In  interac- 
tive situations,  lowercase  typography  for  machine  mes- 
sages and  for  the  echoes  of  user  input  should  be  used 
whenever  possible.  When  all  capital  settings  are  used, 
they  should  be  used  to  highlight  a  restricted  set  of  pri- 
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mary  content  elements,  e.g.,  the  main  title  of  a  frame  or 
the  module  in  which  a  prompt  occurs. 

3.  The  Grid 

As  for  the  design  of  a  traditional  printed  book  page,  the 
graphic  designer  of  software  documentation  must  con- 
sider the  visual  field,  the  terminal  screen  or  the  printed 
page,  as  an  entity  whose  proportion,  size,  and  distance 
from  the  viewer  are  important  to  the  design  of  informa- 
tion. Information  is  presented  in  conceptual  frames  of 
pages  or  screens.  To  assist  the  overall  organization  of 
elements  within  the  frame  and  consistency  from  frame 
to  frame,  a  reference  grid  of  a  few  horizontal  and  verti- 
cal lines  should  be  determined  to  locate  certain 
standard  positions  for  elements  such  as  titles,  prompts, 
etc.  One  of  the  most  important  functions  of  the  grid  is 
to  establish  certain  basic  divisions  of  the  frame.  The 
grid  should  establish  one  or  more  major  columns  of  text 
of  approximately  60  characters  in  width. 

For  fixed-width  character  printers  or  terminals,  one  sim- 
ple approach  to  frame  design  is  to  use  two  primary 
locations:  a  single  major  column  lying  between  charac- 
ter positions  21  to  80  and  a  special  position  at  charac- 
ter position  1  for  all  secondary  matter,  such  as  subti- 
tles for  explanatory  text  or  user  input  for  textually 
oriented  command  and  control  interfaces.  For  subtitling, 
the  reader  can  easily  scan  the  overall  structure  of  the 
document;  for  interfaces,  the  user's  input  and  the 
machine's  responses  are  visually  distinct.  Primary  tab 
settings  of  10  characters  each  and  a  secondary  set 
every  5  characters  can  help  divide  the  entire  visual 
field  into  regular,  modular  units.  Selection  of  upper  or 
lower  case  alphanumeric  characters  and  a  grid  influ- 
ence other  aspects  of  the  typographic  design,  viz., 
character  spacing,  word  spacing,  line  length,  justifica- 
tion, line  spacing,  and  the  overall  spatial  structure  of 
the  frame. 

4.  Words,  Lines,  and  Parrigraphs 

in  stituations  in  which  character  width  is  constant  and 
letterform  design  is  quite  simple,  word  spaces  are  rela- 
tively large  and  lines  of  text  tend  to  fall  apart  into  a 
loose  collection  of  alphanumerics.  Wherever  possible 
the  typographic  design  approach  stresses  the  need  to 
keep  words  that  belong  together  close  to  each  other  in 
word,  line,  and  paragraph  groupings.  For  example,  only 
one  word  space  is  sufficient  after  a  period  in  continu- 
ous prose  to  separate  the  end  of  one  sentence  and  the 
beginning  of  the  next.  The  graphic  design  approach 
also  seeks  to  emphasize  clear  spatial  groupings  over 
the  entire  visual  field  in  order  to  make  distinctions  of 
content.  At  the  same  time  these  spatial  groupings  are 
limited  in  their  variation  so  that  there  is  an  overall 
visual  consistency  or  rhythm  within  and  between 
frames. 

A  typical  oversight  in  most  textual  displays  is  using 
text  lines  of  too  great  a  width.  Normally  there  should  be 
approximately  40-60  characters  per  text  line  (about 
10-1 2  words)  [3,  29].  Research  has  shown  [3,  33] 
that  unjustified  (unequal  length)  text  lines  are  just  as 
legible  as  justified  text.  In  the  case  of  fixed  width 
characters,  justification  usually  means  that  large  gaps 
of  empty  space  appear  between  words  in  order  to 
achieve  equal  width  text  lines.  These  large  spaces 
interrupt  eye  movement  and  impede  reading.  Especially 


for  interrupted  text,  typographic  design  calls  for  unjus- 
tified paragraphs.  This  design  feature  has  the  added 
effect  of  making  character  positio^  21  visually  the 
most  important  in  the  frame.  An  implied  vertical  line  of 
the  beginnings  of  text  lines  appears  at  this  position. 
This  becomes  the  location  for  many  key  words,  text  line 
beginnings,  etc.  The  reader  quickly  develops  the  habit 
of  scanning  this  location  for  most  beginnings  of  informa- 
tion. 

In  fixed  character  width,  fixed  interline  spacing  situa- 
tions, the  space  between  groups  of  lines  has  limited 
variation.  Whenever  possible  one  should  avoid  any 
spacing  larger  that  a  single  line  skip.  This  may  be  used 
between  paragraphs,  line  clusters,  individual  sets  of 
menu  prompts,  user  responses,  etc.  In  this  way  a  max- 
imum number  of  text  lines  per  frame  can  be  utilized. 
Note  that  the  horizontal  line  made  of  hyphens  can 
replace  a  skipped  text  line  and  does  not  add  another 
line  to  the  already  limited  number  of  lines  in  a  frame. 

5.  Tables  and  Lists 

A  major  design  principle  is  to  limit  the  amount  of  varia- 
tion wherever  possible.  This  applies  especially  to  tabu- 
lar settings  for  tables  and  lists.  In  the  case  of  fixed 
character-width  situations,  the  most  important  words  or 
word  groupings  are  placed  at  or  near  (i.e.,  before  or 
after)  the  tab  setting  at  the  21st  character  position. 
All  tables  and  lists  require  headings  to  describe  the 
contents  in  general  and  to  identify  the  parts  if  there 
are  many.  These  titles  should  not  scroll  off  the  screen 
or  disappear  from  continued  pages;  they  should  be 
regenerated  as  needed  so  that  each  frame  includes 
sufficient  titles  to  be  comprehendable.  All  horizontal 
positioning  of  tables  and  lists  is  governed  by  the  desire 
to  keep  codes,  page  numbers  or  other  symbol  groups 
close  to  the  items  to  which  they  refer  and  to  allow  easy 
scanning  down  and  across  items. 

6.  Examples 

The  principles  outlined  above  are  embodied  in  two  sets 
of  accompanying  examples.  One  set  involves 
redesigned  formats  for  the  low  resolution  online  inter- 
face [4]  to  an  information  management  network  which 
accesses  very  large  geographic  databases  [5].  The 
other  set  arises  from  prototype  redesigns  of  textual 
programs  for  display  on  high  resolution  terminals  or 
printers.  A  comparison  between  old  and  new  versions 
will  clarify  how  earlier  designs  for  frames  were  faulty 
and  inconsistent.  Improvements  in  the  newer  versions 
should  be  obvious.  The  examples  appear  in  the  accom- 
panying Figures. 

7.  Conclusions 

Most  of  the  changes  in  the  documentation  formats  have 
been  relatively  easy  to  implement  within  the  software. 
These  redesign  features  are  more  than  a  'cosmetic' 
facelift  to  the  system.  By  carefully  considering  not 
only  what  to  show,  but  also  when,  how,  and  why  to 
show  it,  a  better  understanding  of  the  functionality  of 
the  system  emerges  in  the  minds  of  the  builders  and 
ultimately  in  the  minds  of  the  users  of  the  computer 
system. 

Many  of  the  changes  in  design  constitute  working  con- 
ventions rather  than  carefully  proven  standards.  How- 
ever, in  the  case  of  the  first  set  of  examples,  many  of 
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the  changes  corresponded  to  recommendations  of  an 
independent  critique  of  the  system  [6,  54-55].  In  the 
second  set  it  is  also  clear  from  informal  discussions 
with  users  and  implementors  of  computer  systems  that 
changes  brought  about  by  consideration  of  typographic 
design  principles  have  made  clear  improvements  that 
programmers  as  well  as  users  can  readily  perceive.  As 
these  design  principles  and  specifications  for  new 
documentation  standards  are  more  completely  deter- 
mined, they  can  be  embodied  in  a  graphic  design  manual 
[7].  This  manual  could  assist  future  builders  of  docu- 
mentation modules  to  maintain  a  consistent,  high  quality 
inter-face  or  inner-face  for  the  computer  system. 
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Rgure  1  a:  Undesigned  Command  Menu  Descriptions 
Frame 

Within  the  Computer  Science  and  Mathematics  Depart- 
ment of  Lawrence  Berkeley  Laboratory,  the  author  (who 
has  a  professional  background  in  graphic  design)  has 
begun  to  apply  the  principles  of  information-oriented 
typographic  design  to  the  redesign  of  the  interface  for 
a  large  experimental  geographic  information  manage- 
ment system  called  Seedis  [5].  The  interface  for 
Seedis  has  gone  through  several  stages  since  its 
genesis  as  a  series  of  stand-alone  batch  programs  in 
1972,  particularly  as  it  expanded  its  functional  capa- 
bilities. The  current  version  of  Seedis  operates  in  an 
interactive  VAX/VMS  environement  with  a  textual  (i.e., 
essentially  alphanumeric)  interface.  Seedis  permits  a 
relatively  computer-naive  person  to  examine  data  dic- 
tionaries, extract  data  from  databases,  to  aggregate  or 
disaggregate  data  between  different  levels  of  detail, 
and  to  display  the  selected  data  as  a  labeled  table,  dot 
matrix  chart,  pie  chart,  line  chart,  bar  chart,  or 
area/symbol  choropieth  map.  In  the  Figure,  note  the  ille- 
gibility of  all  capitals  in  comparison  to  upper  and  lower 
case  and  the  interrupted  list  of  command  definitions. 

Figure  1  b:  Designed  Command  Menu  Descriptions 
Frame 

The  command  menu  description  frame  appears  when  the 
user  types  a  question  mark  at  any  decision  point,  i.e.,  if 
there  is  some  confusion  about  the  proper  response  to 
the  immediately  preceding  prompt.  Note  the  organized 
appearance  of  text  groups,  the  order  of  text  elements, 
the  use  of  rules,  lower  case,  and  specific  tab  settings. 
The  full  screen  width  is  equivalent  to  80  typewritten 
characters  in  width.  Information  on  global  commands  is 
introduced  in  the  very  first  information  to  the  user.  The 
standard  form  of  the  menu-prompt  identifies  the  module 
(all  capital  letters)  in  which  the  user  is  currently 
working  and  the  appropriate  commands  at  this  point. 
Note  the  use  of  the  standard  tab  settings  at  position  1 
and  21  and  the  consistent  use  of  standardized  verbs 
to  describe  the  input  commands.  Global  commands  are 
separated  from  local  commands  appropriate  to  the  par- 
ticular decision  point.  The  list  is  labeled  to  aid  identifi- 
cation of  its  component  parts. 
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? 

TYPE  ONE  OF  THE  FOLLOWING  COMMANDS... 
?  FOR  THIS  LIST  OF  COMMANDS 

HELP  FOR  HOW  TO  GET  HELP 

MORE  TO  SEE  NEXT  SCREENFULL 

TABLE  FOR  THE  TABLE  OF  CONTENTS 

<N>  FOR  PAGE  <N> 

•   < COMMENT)  TO  ENTER  A  COMMENT   IN  THE  LOG 
DATA  <SEOUENCE  LETTERS >  SELECT  DATA  CODES 

CANCEL  < SEQUENCE  LETTERS)  CANCEL  DATA  CODES 

FOR  X   <C>       SUBSTITUTE  C  FOR  X   IN  DATA  CODES  - 

ALSO  XX  XXX  XXXX  Y  YY  YYY  YYYY 
REVIEW  LIST  DATA  SELECTIONS  MADE  SO  FAR 

SAVE  SAVE  DATA  SELECTIONS  AND  RETURN 

QUIT  CANCEL  DATA  SELECTIONS  AND  RETURN 

READY 


DATA:   <line  letter (3)>,  table,   <page  number),  CR 

:  ? 


Input  Description 


<line  letter (s))        select  one  or  more  data  elements  by  line  letter 

table  display  table  of  contents  for  this  database  code 

<page  number)  display  a  particular  page 

CR  (carriage  return)  display  the  next  page 

?  list  avalable  commands  in  this  menu 

help  describe  data  element  selection 

show  display  table  of  contents  for  this  database 

review  list  current  data  element  selections  and  history 

cancel  delete  current  data  element  selections  for  this  database 

quit  return  to  database  selection  menu 


DATA:   <line  letter (s)),  table,   <page  number),  CR 
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READY 

MON I TOR . SEED I S . HELP . 


INTRODUCTION  TO  SEED IS 
The  three  major  processes  in  SEEDIS  are: 

AREA:  define  a  geographic  study  area  (composed  of  states, 
counties,  or  census  tracts) 

DATA:  select  data  appropriate  to  the  geographic  study  area 

chosen.  For  example,  for  a  study  area  consisting  of  a  group 
of  states,  only  state  level  data,  and  not  county  or  tract 
level  data,  are  appropriate. 

DISPLAY:  manipulate  and  display  the  data  in  table,  chart,  graph, 
and/or  map  form. 

Normally  AREA,  DATA,  and  DISPLAY  are  performed  in  the  order 
given.  However,  once  the  geographic  study  area  is  defined  (AREA), 
one  may  alternate  between  DISPLAY  and  the  selection  and 
extraction  of  additional  items  in  DATA. 

TYPE  MORE  TO  SEE  NEXT  SCREENFULL 

TYPE  ?  FOR  A  LIST  OF  COMMANDS 


help 


SEEDIS:  area,  data,  display,  profile 
USING  SEEDIS 


LBL's  Seedis  is  an  experimental  information  system  that 
includes  integrated  program  modules  for  retrieving,  analy- 
zing, and  displaying  selected  portions  of  geographically 
linked  databases.  Program  modules  in  Seedis  include: 

area  select  geographic  area  (level  and  scope  of  analysis) 

data  select,  extract,  enter,  or  transform  data 

display  manipulate  and  display  data  in  tables,  maps,  and  charts 

profile  produce  standard  socio-economic  reports  for  selected  areas 

Normally  Area,  Data,  and  Display  are  used  in  the  order 
given.  However,  once  the  geographic  study  area  is  defined 
in  Area,  you  may  alternate  between  Display  and 
the  selection,  extraction,  or  entering  of  additional  items 
in  Data. 

SEEDIS:  area,  data,  display,  profile 


Figure  2a:  Undesigned  Help  Messages  Frame 

Note  the  long  lines  of  text,  the  clutter  In  the  last  para- 
graph caused  by  clumps  of  all  capital  words,  the  gaps 
in  word  spacing  caused  by  justification,  and  the  mix- 
ture of  small  indentations  with  centered  headlines. 

Figure  2b:  Designed  Help  Messages  Frame 

Help  messages  are  a  standard  one  frame  page  descrip- 
tion. Note  the  use  of  standard  tab  settings,  unjustified 
text,  the  use  of  all  capital  headline  together  with 
hyphen  line,  removal  of  all  capital  keywords  (replaced 
by  exdented  words,  i.e.,  positional  emphasis),  and  the 


use  of  second  person  in  English  language  style.  Further 
frames  of  information  are  available  on  the  four  key 
words  listed. 

Figure  3a:  Undesigned  Textual  Program 

This  figure  presents  a  typical  C  program  in  an  elemen- 
tary typographic  form  using  fixed-width  characters  of  a 
single  size  and  typeface  with  limited  horizontal  spacing 
variation.  There  is  little  typographic  hierachy.  The  pro- 
gram is  more  readable  than  those  presentations  that 
use  all-capital  typography  and  multiple  commands  per 
line,  but  there  are  still  ways  in  which  it  can  be  made 
more  readable. 
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Figure  3b:  Designed  Textual  Program 

This  figure  siiows  a  prototypical  black-and-wliite  visu- 
alization tliat  would  require  a  iiigli  resolution  bit  map 
display  terminal  or  a  very  higli  resolution  hardcopy  dev- 
ice. Tlie  actual  image  was  generated  in  Times  Roman 
type  using  a  computer-controlled  phototypesetter,  a 
rcire  but  not  unheard  of  hardcopy  device.  This  image  is 
one  of  a  series  of  experimental  prototype  frames  for 
offline  or  online  documentation  that  illustrates  the  full 
potential  of  a  graphic  design  aproach  to  textual  pro- 


gram visualization.  The  image  was  designed  by  the 
author  and  Dr.  IRonald  Baeclcer  with  Mr.  Richard  Snider- 
man  of  Human  Computing  Resources  Corporation.  Spatial 
location,  typographic  symbol  hierarchies,  figure-field 
enhancements,  indexes,  abstracts,  etc.,  are  combined 
to  create  a  clear,  consistent,  explicitly  structured 
frame  that  is  legible  and  appeaing  to  the  reader,  based 
on  a  limited  number  of  disussions  with  programmers  who 
have  viewed  but  not  used  this  presentation. 
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NBS  FIPS  Software  Documentation  Workshop 


March  3,  1982 


Quality  Issues  in  On-line  Documentation 


Joseph  Psotka  ,  Ph.D. 


National  Institute  of  Education 
1200   19th  St.   N.  W. 
Washington,  D.   C.  20208 

With  the  increasing  use  of  microcomputers  in  all  areas,  the 
computer  is  taking  on  aspects  of  an  appliance  that  only  needs 
instructions  to  set  up  and  then  starts  to  work.  This  makes 
on-line  documentation  an  important  area  for  research. 
Suggestions  are  made  here  for  the  human  factors  aspects  of 
on-line  documentation,  including  a  metaphor  for  guiding  novice 
users;  abbreviated  menus  for  expert  users;  error  messages  that 
are  polite;  HELP  statements  that  do  not  erase  the  current 
display;  interfaces  that  respond  to  natural  language  statements; 
and  input-output  devices  that  make  use  of  general  skills. 
Although  this  view  of  documentation  exceeds  traditional  print 
perspectives  ,  it  may  be  necessary  to  see  documentation  as  part  of 
the  structure  of  a  program  when  it  goes  on-line.  These  issues  are 
discussed  within  the  context  of  an  educational  software  authoring 
system . 

Keywords:  On-line  documentation,  Human  Interface,  Authoring 

1.  INTRODUCTION 


On-line  documentation  is  becoming  increasingly  possible  and 
increasingly  necessary.  It  is  becoming  possible  because 
microcomputers  are  appearing  as  dedicated  machines  that  are  used 
primarily  for  one  function  rather  than  as  general  purpose 
computers.  As  Heines  (1981)  has  phrased  it,  the  personal 
computer  or  microcomputer  has  begun  to  take  on  the  distinctive 
characteristics  of  an  appliance.  This  means,  in  part,  that  the 
users  of  the  computer  are  much  more  naive  about  computers  than 
traditional  users ,  and  they  may  have  attitudes  shaped  by  the  use 
of  other  appliances,  like  refrigerators  and  television  sets,  that 
lead  them  to  expect  it  to  work  in  certain  ways.  In  particular, 
they  may  expect  (and  perhaps  deserve)  to  have  the  training  and 
documentation  incorporated  right  into  the  running  of  the  system. 
This  raises  human  engineering  problems  whose  solution  are  only 
vaguely  visible  at  this  time. 


Note:  The  views  and  opinions  in  this  paper  are  those  of  the  author, 
expressed  in  a  personal  capacity,  and  do  not  necessarily  reflect  the  policy 
of  the  National  Institute  of  Education,  Office  of  Educational  Research  and 
Improvement . 
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This  article  is  structured  by  using  a  functional  analyses  that  examines 
the  needs  of  an  authoring  language  from  the  perspective  of  its  three  major 
users:  the  author (s),  the  teacher,  and  the  student.  Each  of  these  users  has 
their  own  set  of  needs  in  using  the  computer,  but  the  needs  all  combine  in 
the  sense  that  training  and  documentation  must  be  made  a  part  of  the  system, 
if  the  authoring  language  is  really  to  be  useful.  By  examining  how 
documentation  might  be  made  part  of  a  educational  software  authoring  system 
in  detail,  general  characteristics  of  on-line  documentation  may  become  more 
apparent.  Some  of  these  general  issues  are  raised  in  the  first,  overview 
section . 


2.   GENERAL  ISSUES 


2.1.  Overview 

Writing  software  for  education  (usually  called  courseware)  is  a  highly 
labor  intensive  enterprise,  like  teaching  itself.  An  authoring  language  that 
would  allow  teachers  to  write  the  programs  is  needed  to  reduce  courseware 
costs,  increase  quality,  and  widen  the  range  of  materials  available.  The 
authoring  system  should  also  allow  the  software  to  be  run  on  a  variety  of 
machines  (increasing  transportability).  Therefore  it  needs  to  be  used  by 
teachers  who  want  to  use  others'  courseware.  Finally,  it  should  interact 
with  the  student  to  help  him  use  the  courseware  written  by  the  teachers. 
Thus,  the  authoring  system  needs  to  deal  with  many  novice  users  who  may  have 
no  detailed  conception  of  what  a  computer  is,  nor  what  its  limitations  are. 

2.2  Overall  Metaphor 

Novice  users  will  come  to  the  system  with  expectations  that  derive  from 
their  past  experience  in  doing  similar  things.  These  intuitions  need  to  be 
used  carefully  to  make  the  system  easier  to  learn  and  document.  For  the 
authors,  a  guiding  metaphor  might  be  developed  that  used  their  experience  in 
writing  a  book,  with  its  various  activities  of  gathering  material,  writing 
content,  illustrating,  editing,  publishing,  proofing,  and  rewriting.  For  the 
teacher,  the  appropriate  metaphor  might  be  to  see  the  authoring  system  as  a 
novice  teacher  that  needs  help  and  supervision.  For  the  student,  the 
appropriate  metaphor  might  be  to  see  the  authoring  language  as  a  teacher's 
aid,  to  provide  audiovisual  displays,  adjust  the  lights,  and  provide 
additional  exercises  and  explanatory  material.  Each  user  should  have  a 
metaphor  that  makes  it  easier  to  learn  the  system. 

2.3  HELP  Access 

HELP  functions  are  common  to  many  systems,  but  they  usually  are  quite 
subordinate  to  separate  documentation  that  really  describes  how  the  system 
works.  If  documentation  is  really  to  be  made  on-line,  then  HELP  functions 
must  be  reconceptuali zed  to  provide  more  detailed  and  useful  information  to 
novices  users  who  have  not  read  external  documentation.  Aside  from  general 
orientation  metaphors  and  descriptions,  and  prompts  about  what  to  do  next, 
the  HELP  functions  may  also  need  to  simulate  certain  activities  so  that  the 
novice  can  step  through  the  function  and  obtain  information  about  how  the 
process  should  be  conducted  in  some  optimal  way. 

Current  approaches  to  help  functions  have  some  severe  shortcomings.  One 
general  feature  of  HELP  functions  I  have  used  is  that  they  require  addressing 
a  menu  or  a  directory  that  forces  one  to  leave  the  active  display  or 
workspace.  A  novice,  in  particular,  cannot  be  expected  to  remember  the  exact 
characteristics  of  his  work  leading  up  to  the  problem.  Even  experienced 
users  may  have  this  problem.  At  the  very  least  a  windowing  technique  should 
be  used  to  leave  the  display  more  or  less  intact  while  displaying  the  HELP 
information  as  well.  This  feature  is  even  more  important  when  the  HELP 
function  has  to  simulate  a  particular  activity  while  the  user  is  actually 
engaged     in     that     activity.       With     a     split     screen     or  window  that  provided 
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carefully     prepared     illustrations  of     a     function,     while     the     user  could 

actually  carry     out  the     function,  training     and  documentation     could  reach  a 

level  of  efficiency  that  might  be  comparable  with  live  instruction  by 
teachers  and  experts. 

2.4  ERROR  messages 

Error  messages  are  one  of  the  most  discouraging  and  problem  filled  areas 
of  documentation.  The  error  messages  I  have  encountered  are  both 
discourteous  and  uninf ormati ve .  Messages  like  "OPERATION  ABORTED"  leave  me 
with  the  feeling  that  I  may  have  just  participated  in  a  sleazy  and  illegal 
procedure.  Of  course,  these  messages  are  intended  for  experts  and  other 
cognoscenti ,  but  on-line  documentation  may  mean  that  novices  will  encounter 
these  obscure  comments  more  often.  This  seems  to  a  fairly  good  reason  for 
integrating  these  Error  messages  with  the  larger  body  of  HELP  functions  that 
are  available.  The  error  message  might  recommend  which  HELP  function  to 
use.  Even  if  documentation  is  not  on-line,  it  would  seem  to  be  a  very 
useful  thing  to  have  error  messages  refer  to  page  numbers  in  a  documentation 
manual  that  could  provide  some  timely  assistance. 

2.5  Personalizing  Assistance 

Much  documentation  is  written  in  a  very  impersonal  style.  There  are  some 
indications  that  this  style  is  inappropriate  when  documentation  is  on-line. 
Users  have  a  very  strong  tendency  to  anthropomorphize  their  interactions 
with  computers:  they  tend  to  think  of  computers  as  another  human  being. 
Computer  programs  are  beginning  to  take  this  forceful  tendency  into  account 
by  personalizing  interactions.  Computers  will  often  ask  for  a  user's  name 
and  respond  with  that  name  in  providing  information.  It  is  my  judgment  as 
well  as  others'  (c.f.  Nickerson ,  1981)  that  this  superficial  personalization 
may  carry  some  heavy  costs  as  well  as  benefits.  For  instance,  it  encourages 
users  to  think  that  computers  are  smarter  than  they  really  are.  But  in 
terms  of  on-line  documentation,  this  kind  of  personalization  is  probably 
necessary . 

Providing  help  and  assistance  is  something  that  always  needs  to  be  done 
gracefully,  especially  when  it  comes  from  an  inanimate  object.  Terse  error 
messages  are  no  way  to  soothe  someone's  frustration  at  being  unable  to 
complete  a  task  smoothly.  So  personalization  should  be  carried  more  deeply 
into  sensitive  social  interaction.  Liberal  use  of  thank  you,  sorry,  and 
please  is  probably  highly  appropriate.  It  would  probably  be  wise  to  adapt 
the  documentation  style  to  the  user's  style;  on  such  characteristics  as 
politeness,  longwindedness ,  and  directness.  But  this  is  taking  us  a  little 
beyond  the  scope  of  this  paper. 

2.6  Natural  Language 

Artificial  intelligence  and  psycholinguistic  research  has  made 
significant  strides  toward  developing  methods  for  natural  language 
understanding  in  computers.  It  is  not  unreasonable  that  this  research  might 
soon  find  applications  in  on-line  documentation.  This  is  particularly 
important  for  novice  users  of  the  systems.  It  is  probably  most  important 
for  structuring  HELP  functions.  There  are  also  functional  alternatives  to 
the  implementation  of  complex  systems  for  natural  language  understanding. 
One  alternative  is  to  compile  a  complete  list  of  the  questions  that  novices 
tend  to  ask  about  a  particular  system.  This  approach  has  been  implemented 
by  Ford  (1982)  at  Johns  Hopkins  with  checking  account  and  library  indexing 
programs.  The  limitation  to  this  approach  lies  in  the  memory  capacity  of 
the  computer.  This  is  a  significant  limitation,  but  complete  language 
understanding  is  not  the  objective  of  this  approach.  A  limited 
understanding  can  still  be  very  useful  for  novices. 
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3.      SPECIFIC  REQUIREMENTS 


3.1  Overview 


Documentation  of  an  authoring  system  must  take  into  account  situations 
that  may  arise  in  producing  software  for  instruction.  It  is  not  clear  that 
these  are  general  issues,  although  some  aspects  may  be  applicable  to  the 
documentation  of  a  large  variety  of  programs. 


3.2  Defining  the  User 


In  order  to  individualize  on-line  documentation  and  make  it  optimally 
functional,  it  is  important  to  define  the  purposes  the  software  is  to  serve 
for  a  particular  user.  In  an  authoring  system,  the  documentation  should 
first  assess  whether  the  user  is  a  teacher,  student,  or  courseware  writer. 
Not  only  should  specific  software  functions  be  tied  to  this  assessment  (so 
that  a  student  cannot  change  the  answers ,  for  instance  )  but  the 
documentation  should  be  keyed  to  this  assessment  too.  If  a  metaphor  is 
being  used  to  make  the  software  functions  more  comprehensible,  then  the 
on-line  documentation  should  be  phrased  in  that  metaphor. 

In  an  authoring  system  there  will  be  many  kinds  of  teachers  and  students 
using  the  system.  To  some  extent  their  characteristics  cannot  be  predicted. 
But  there  will  also  be  a  large  number  of  different  courseware  writers ,  and 
these  can  be  more  easily  predicted  and  described.  For  instance,  there  will 
be  instructional  experts,  programmers,  media  specialists,  cognitive 
scientists,  and  graphic  designers.  The  documentation  should  support  the 
demanding  characteristics  of  each  professional. 

Defining  the  user  also  means  defining  the  expertise  of  the  user.  A 
simple  menu  may  be  the  most  efficient  information  that  an  expert  can  have, 
but  a  first-time  user  may  well  need  very  lengthy  explanations  and  examples 
to  demonstrate  specific  functions.  Defining  the  user  can  therefore  be  a 
very  complicated  exercise,  but  a  very  important  one.  There  is  very  little 
in  this  world  that  is  as  frustrating  as  asking  for  a  HELP  function  that 
gives  messages  that  are  not  very  helpful.  Of  course  it  can  be  unhelpful  in 
many  ways:  for  instance,  it  can  provide  information  I  already  know,  or  it 
can  provide  information  that  I  do  not  understand.  Both  are  frustrating. 
The  best  kind  of  documentation  would  provide  information  that  I  need  before 
I  know  enough  to  ask  for  it.  It  seems  to  me  that  this  should  be  possible, 
if  the  needs  and  knowledge  of  the  user  are  carefully  defined  beforehand. 


3.3  Defining  the  Structure 


It  is  not  enough  that  documentation  should  help  someone  use  the  system, 
it  should  also  make  the  user  expert.  In  part,  this  can  be  done  by  defining 
the  user,  and  if  he  is  a  novice,  providing  instruction  that  makes  him  more 
expert  by  training  and  education.  However,  the  system  documentation  should 
also  help  structure  the  system  product  so  that  the  final  result  has  expert 
characteristics.  It  is  difficult  at  this  point  to  distinguish  tetween 
system  function  and  documentation,  but  this  will  be  an  ongoing  difficulty  of 
distinction  in  any  on-line  documentation  system. 

Since  documentation  is  integrated  with  system  training  and  performance; 
the  more  thorough  the  integration  the  more  difficult  it  will  be  to  draw  a 
line  between  system  function  and  documentation.  Since  an  authoring  system 
is  designed  to  produce  more  software,  the  documentation  should  provide  a 
natural  encouragement  of  good  design  practices  like  structured  programming, 
and  object-oriented  code.  Portions  of  courseware  will  be  reusable  in 
different  implementations,  and  modular  construction  will  make  the  transfer 
of  frequently  used  portions  more  convenient.  Similarly,  documentation  will 
need  to  provide  advice  about  how  to  make  the  software  more  tansportable ,  so 
that  it  can  be  implemented  on  a  wide  range  of  currently  available  machines. 
These  are  only  a  few  of  the  structural  characteristics  that  documentation 
can  help  achieve. 
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3.4  Defining  the  Feedback 


An  authoring  system  that  responds  to  the  needs  of  a  student  actually 
using  the  educational  software  will  require  feedback  and  analysis  systems 
that  go  far  beyond  the  traditional  requirements  of  HELP  functions.  A 
student  will  always  need  access  to  a  real  teacher,  who  can  answer  a  question 
like  "What  did  I  do  wrong?".  However,  some  level  of  machine  tutor  will  also 
need  to  be  built  into  the  system.  Intelligent  coaching  can  be  added  in  many 
ways.  At  a  primitive  level,  a  trace  of  the  sequence  a  student  followed  can 
provide  some  meaningful  feedback.  At  a  more  complicated  level,  the  system 
can  analyze  the  errors  a  student  made  to  try  to  find  consistent  errors  or 
"bugs"  in  thinking  (Brown  &  Burton,  1978;  Feurzeig,  Horwitz,  &  Nickerson, 
1981).  On-line  documentation  at  this  level  will  require  very  sophisticated 
understanding  of  a  student's  needs  in  order  to  explain  how  to  use  an 
intelligent  tutor  like  this.  Clearly,  this  kind  of  documentation  will  grow 
in  complexity  with  the  increasing  level  of  understanding  that  a  student  has. 
The  documentation  itself  will  become  part  of  the  individualized  instruction. 
One  of  the  most  important  aspects  of  this  documentation  may  well  be  the 
growth  in  self-knowledge  that  it  promotes. 


3.5  Defining  the  Input/Output 


One  of  the  most  difficult  and  important  aspects  of  effective  instruction 
lies  in  the  appropriate  selection  of  input  and  output  devices  appropriate  to 
a  particular  activity.  With  the  large  number  of  devices  currently  available 
(keyboard,  joystick,  lightpen,  digitizer,  mouse,  and  voice  input;  printer, 
videodisc,  plasma,  graphic,  music  and  voice  output)  documentation  of  these 
possibilities  has  become  particularly  complex,  especially  if  the 
documentation  is  designed  to  make  the  process  more  efficient  and  effective 
by  providing  timely  advice.  The  complexity  of  this  documentation  can  be 
suggested  by  examining  just  one  of  these  areas:  graphic  display.  Just 
imagine  the  difficulty  of  introducing  novice  users  and  documenting  the 
following  functions: 

o     Multiple  type  fonts  available  at  full  speed  for  screen  display; 

o  Two-dimensional  objects  made  up  of  points,  line  segments,  circular 
arcs,  and  spline  curves  are  able  to  be  translated,  rotated,  dilated, 
contracted,  and  stretched  anisotropically ; 

o  Three  dimensional  graphics  can  be  used  to  isolate  components,  compute 
areas  and  volumes,  and  demonstrate  multidimensional  functions; 

o     Animation  can  occur  in  real  time; 

o  Complicated,  high  resolution  displays  can  be  retrieved  on-line  from 
videodiscs  and  ROM  packs  or  bubble  memory  modules; 

o  Graphics  packages  for  bar  and  pie  charts  and  graphs  are  available  with 
3-D  display  capabilities. 

The  enormous  capabilities  that  computers  bring  with  them  to  almost  every 
function  of  instruction,  like  these  display  capabilities,  place  a  heavy 
burden  on  documentation.  It  is  a  burden  that  may  well  be  possible  to  carry 
only  if  the  documentation  is  on-line  and  integrated  into  the  system's 
function . 


4.  CONCLUSION 


4.1  This  paper  has  presented  a  brief  overview  and  suggestions  for 
incorporating  human  factors  considerations  into  on-line  documentation. 
These  suggestions  include  a  guiding  metaphor  for  each  user;  integrating  HELP 
functions  into  the  error  messages  for  training  purposes;  personalizing 
interactions  and  making  them  conform  to  the  rules  of  good  conversation; 
using  natural  language  protocols,  particularly  with  novices;  and  providing 
useful,  system-initiated  feedback  and  information  that  reduces  the  enormous 
complexity  of  the  tasks.  These  suggestions  were  discussed  within  the 
context  of  an  educational  software  authoring  system,  but  the  discussion  was 
intended  to  be  general  and  apply  to  many  computer  systems. 
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An  additional  and  very  important  point  that  needs  to  be  raised  in 
conclusion,  especially  in  the  hope  of  stimulating  further  discussion,  is 
that  this  paper  has  not  begun  to  address  the  complicated  problems  of 
potential  relations  between  on-line  documentation  and  print  documentation. 
It  should  be  clear  that  this  has  not  been  an  argument  for  replacing  all 
hard-copy  with  on-line  documentation.  There  is  probably  a  need  for  both. 
On-line  documentation  is  designed  for  users  at  work  on  the  computer,  but 
clearly  students  and  others  will  do  work  at  home  or  in  other  ways  removed 
from  the  computer,  where  hard-copy  and  manuals  are  clearly  cost-effective. 
Just  because  information  can  be  presented  on-line  does  not  necessarily  mean 
that  it  should  be.  The  particular  uses  that  each  serves  best  still  need  to 
be  thought  out  carefully,  and  need  to  evolve  in  response  to  the  changing 
circumstances  of  computer  use. 
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Improving  the  Quality  of  User-Level  Documentation 
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Department  of  Electrical  Engineering  and  Computer  Science 
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The  George  Washington  University 
Washington.  DC  2UUb2 


The  four  papers  in  this  session  are  an  interesting  group.  Further,  the  session 

itself  is  interesting  in  that  it  is  devoted  to  a  discussion  of  user  documentation  in 

a  workshop  whose  primary  purpose  has  been  to  consider  problems  in  develjoper  or 
maintainer  documentation. 


Ty^es  of  Users  and  User  Doc^u^mentati^on. 

Let  me  first  uistinguisn  some  types  of  documentation  by  making  an  analogy  with 
trie  dutuiiiobi  le.    1  know  of  at  least  five  different  major  kinds  of  documentation 
associ  ated  wi  th  cars: 

0    Design  drawings,  made  up  by  the  designer  but  not  detailed  enough  to  build 
the  car  from; 

0    Shop  drawings  or  blueprints,  from  which  the  (subsystems  of)  the  cars  are 
actually  built; 

0   Mechanic's  guides,  or  'shop  manuals"  which  enable  a  professional  mechanic 
to  repair  or  maintain  the  vehicle; 

0   Repair  books  intended  for  the  amateur  mechanic,  which  do  not  detail  repairs 
too  delicate  for  the  do-it-yourselfer  to  attempt; 

0    Driver's  manual,  written  in  lay  terms,  which  tells  how  to  operate  but  not 
repai r  the  automobile. 


In  general,  this  workshop  has  been  concerned  with  documentation  analogous  to 
the  first  four  types,  intended  for  people  designing,  building,  maintaining,  and 
repairing  programs.    The  present  session  is  --  happily  —  concerned  chiefly  with 
documentation  analogous  to  that  in  the  last  category:    documentation  for  people 
usi^nj  programs. 

Now  let  us  limit  the  scope  of  the  discussion  a  bit  by  considering  only  users  of 
i  nteracti  ve  programs  or  systems  (this  is  not  very  limiting  since  most  programs  are 
interactive  these  days  anyway).    In  the  research  we  have  been  doing,  we  have  found 
it  convenient  to  divide  these  users  into  five  groups: 


0    Computer  professionals  like  programmers  or  console  operators; 


242 


0    Trained  operators  in  routine  environments,  like  bank  tellers,  airline 
reservati oni sts,  data-entry  clerks  or  word-processor  operators; 

0    Trained  operators  in  high-risk  or  complex  environments,  like  power-plant 
operators,  air  traffic  controllers  or  military  command/control  operators; 

0  Casual  users,  like  attorneys  or  congressional  staff  using  on-line  retrieval 
systems,  professors  writing  papers  on  word-processors,  or  lay  persons  using 
automated  teller  machines; 

0    Uata  analysts  like  statisticians  or  financial  analysts:    the  so-called 
"powerful  minds  using  powerful  tools". 


With  the  possible  exception  of  the  third  category,  a  typical  interactive  system 
may  have  users  in  all  of  the  classes,  and  at  different  levels  of  expertise.    It  is 
thus  clear  that  we  face  a  non-trivial  problem  in  organizing  documentation  to  suit 
the  special  needs  of  each  class- 


Can  Programmers  Understand  User  Uocumentati^on? 

Experience  also  shows  that  technically-trained  computer  specialists  do  not 
intuitively  know  how  to  prepare  documentation  for  any  of  these  groups.    It  is  a 
common  saying  that  programmers  don't  like  to  document  --  even  for  each  other  --  but 
what  is  left  out  is  that  we  often  don't  give  them  training  in  how  to  document,  or 
even  in  understanding  the  class  of  users  for  whom  they're  documenting. 

I  am  reminded  here  of  a  group  of  experienced  programmers  responsible  for  a 
paycheck-writing  system  in  a  data  processing  service  bureau  I  once  worked  for.  When 
asked  what  their  product  was.  they  responded  "programs",  and  were  quite  taken  aback 
when  we  assured  them  that  their  product  was  "paychecks",  and  that  the  client  was  not 
concerned  whether  those  checks  came  from  a  computer  or  a  quill  pen.  only  that  they 
were  delivered  on  time  with  the  right  numbers  on  them!    This  bit  of 
consciousness-raising  did  help  to  put  them  on  the  track  to  understanding  who  their 
users  and  their  customers  were. 

In  the  university,  while  we  do  not  usually  have  "real"  users  for  whom  the 
students  are  producing  programs,  we  do  have  some  very  real  carrots  and  sticks, 
called  grades,  that  we  can  apply  to  make  certain  that  our  teaching  about 
documentation  is  taken  to  heart.    Indeed.  I  and  many  of  my  colleagues  assign  as  much 
as  5U%  of  a  project  grade  to  the  quality  of  maintainer  and  user  documents.  When 
exposed  to  goou  examples  of  documentation,  carefully  taught  now  to  prepare  them,  and 
given  immediate  positive  and  negative  feedback  about  the  results,  even  programmers 
can  learn  how  to  do  it. 


Comments  on  the  Session  Papers. 

Douglas  Hi nes  has  given  an  interesting  presentation  on  user-document 
preparation  in  the  House  of  Representatives.    His  experience  shows  that  involving 
the  technical  person  to  write  the  first  draft  of  a  document,  then  a  representative 
of  the  user  to  refine  it,  pays  off  handsomely. 

Further,  he  makes  a  good  point  in  noting  that  documentation  has  often  not  been 
used  in  training  new  users;    it  is  clear  that  incorporating  the  user  documents  into 
user  training  helps  the  users  to  learn  their  way  around  the  documents  at  the  same 
time  they're  learning  their  way  around  the  system.    This  is  important. 
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i  nad  hoped  to  hear  more  discussion  aoout  on-1 i  ne  documents  in  the  House. 
Kieir  retrieval  systems  appear  to  be  really  modern  and  interactive  from  the  start; 
I'm  thus  a  bit  surprised  that  there  is  so  much  emphasis  on  paper  documentation. 

I'louern  research  on  interactive  systan  development  suggests  that  the  right 
"hooKs"  to  on-line  documentation  need  to  be  integrated  at  desjg^n  ti_nie;    I  hope  to 
see  more  of  this  notion  applied  in  the  government  information  systems  of  the  future. 

It  is  not  in  the  least  to  denigrate  the  fine  work  done  by  Hines  and  his 
colleagues  to  note  that  papers  such  as  this  were  being  written  ten  and  fifteen  years 
ago.    Quite  the  contrary,  it  is  clear  that  the  need  for  papers  liKe  this  is  still 
great;    users  are  not  yet  satisfied  with  the  quality  of  their  documentation.  Hines' 
work  is  then  evidence  of  the  persistence  of  a  knotty  problem. 

I  have  attended  a  number  of  talks  by  Aaron  Marcus,  for  audiences  varying  from  a 
small  research  group  (my  own)  to  several  huge  conferences.    Every  time  I  see  his 
visuals,  hear  him  talk,  or  read  his  papers,  1  am  intellectually  challenged  anew.  As 
a  dyed-in-the-wool  computer  specialist,  I  am  always  amazed  at  how  little  I  really 
know  of  the  world  of  graphic  presentation  (indeed,  how  little  we  in  computing  know 
collectively  about  that  world). 

Marcus'  work  in  interpreting  graphic  arts  to  computer  professionals  —  and 
computers  to  graphic  artists  —  is  very  important  in  this  era  of  relatively 
inexpensive  but  powerful  graphic  displays,  and  in  an  era  of  increasing  concern  about 
the  human  factors  of  user  interfaces  and  the  usability  of  user  documentation.  His 
position  as  a  working  member  of  a  group  building  interactive  systems  is  a  good 
example  of  the  steps  enlightened  technical  managers  can  take  to  improve  the  visual 
quality  of  their  systems,  and  thus  their  acceptability  to  the  user  communities  for 
which  they  are  intended. 

The  university  research  group  1  direct  with  my  colleague  James  Foley  —  a 
world-class  computer  graphics  expert  --  is  working  on  tools  to  improve  the  quality 
of  user  interfaces,  including  on-line  documentation.    The  group  has  been  exposed 
several  times  to  Marcus"  teaching,  and  their  very  adept  incorporation  of  many  of  his 
recommendations  into  their  own  system  designs  is  good  evidence  that  hard-core 
programmers  can  easily  learn  to  apply  good  graphic  design  principles  for  use  even  on 
simple  alphanumeric  terminals  or  teleprinters.    I  hope  to  see  much  more  of  this 
"technology  transfer"  between  computer  people  and  graphic-arts  people  in  the  future. 

Charles  L)i ckson  has  given  us  another  example  of  the  benefits  of  cooperation 
between  computer  specialists  and  people  with  other  talents  --  here  cartoonists  --  to 
produce  big  improvements  in  the  quality  of  documentation. 

From  the  comic-book  manuals  designed  for  semi -1 i terate  World  War  II  draftees. 
Dickson  has  taken  us  to  IBM's  experiment  with  comic-book  manuals  for  some  of  their 
researchers  who  are  very  literate  indeed.    If  a  comic  book  style  can  make  learning 
to  use  a  new  piece  of  equipment  fun,  or  will  encourage  users  to  read  their 
documentation,  then  by  all  means  let  us  experiment  more  with  it.    The  success  of  The 
Fortran  Coloring  Book  by  Roger  Kaufman  in  introducing  college  students  to  the  ins 
and  outs  of  this  widely-used  programming  language  serves  to  emphasize  the  potential 
that  is  there. 

Dickson's  comment  that  documentation  standards  ought  to  be  more  encouraging  to 
those  wishing  to  experiment  with  less  conventional  styles  deserves  careful 
consideration  by  the  committees  which  draft  these  standards. 

Finally.  Joseph  Hsotka  has  given  us  a  provocative  glimpse  into  the  world  of  the 
behavioral  scientists  and  their  thoughts  on  how  to  incorporate  sound  human  factors 
into  on-line  documentation. 
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As  we  move  increasingly  into  a  world  of  interactive  computer  systems  used  by 
people  who  are  not  computer  experts,  on-line  documentation  will  become  a  key  issue. 
Indeed,  it  has  become  clear  from  recent  research  that  the  separation  between  on-line 
documentation  and  the  on-line  system  itself  is  unwarranted.    More  and  more,  on-line 
documentation  is  an  i ntegral  g^art  of  the  system  itself,  and  needs  to  be  carefully 
considered  from  the  very  earliest  stages  of  design  of  the  system. 

Psotka's  comments  about  the  unhelpful ness  of  "HELP"  are  especially  important; 
so  are  his  remarks  about  current  systems'  forcing  the  user  to  abandon  the  context  of 
his  problem  to  request  HELP.    Every  system  designer  should  take  a  long  look  at  the 
recent  developments  in  the  field  of  so-called  "personal  work  stations'  like  the 
Xerox  Star,  to  get  iaeas  about  how  on-line  assistance  can  be  incorporated  into  the 
dialogue  through  windowing  and  context  retention. 

For  detailed  discussion  of  this  and  related  problems,  the  reader  is  directed  to 
the  recent  book  Software  Psychology  by  Ben  Shneiderman,  and  to  the  classic  work  The 
Psychology  of  Computer  Programmi  ng  oy  berald  ^^einoerg. 


nummary. 

Mil  in  all  tnis  is  a  fascinating  and  provocative  group  of  papers,  uur 

attention  has  been  very  effectively  focussed  on  several  of  the  many  important  issues 

in  user  aocunientation.    There  are  a  lot  of  suggestions  here  to  take  to  heart. 
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Session  H:    Quality  Assurance  for  Documentation 

Introduction 

Virginia  C.  Walker 

Quality  Assurance  Division 
Office  of  Statistical  Standards 
Energy  Information  Administration 
Department  of  Energy 

Documentation  and  its  quality  is  often  predictive  of  the  quality  of  the  system  that  it 
purports  to  document.    This  session  approached  quality  assurance  for  documentation  from 
several  directions,  remembering  that  to  perform  quality  assurance  measurement,  one  must 
have  in  mind  quantitative  and  qualitative  criteria. 

In  times  past,  there  has  been  general  concensus  that  people  could  agree  what  a  document 
ought  to  contain,  via  the  checklist  or  table  of  contents  approach,  but  how  to 
universally  decide  whether  a  document  was  good  or  bad  remains  elusive.  Documentation 
could  be  ascertained  to  be  good,  or  bad,  on  a  case  by  case  basis,  but  the  reasons  why 
it  was  good  or  bad  were  equally  hard  to  describe. 

In  this  session,  the  measurement  of  documentation  quality  was  approached  from  several 
directions.    Richard  J.  Thompson  described  an  effort  to  evaluate  the  documentation  at 
the  Chemical  Abstract  Service;  Caroline  S.  Levenson  of  Edition,  Inc.  described  her 
firm's  experience  in  preparing  user  documentation  for  a  varied  clientele  and  relevant  , 
aspects  common  to  them;  and  Herbert  Hecht  of  SoHaR,  Inc.  proposed  a  management  tool  for 
successful  achievement  of  requirements  documentation.    Then  John  R.  Gabriel  of  Argonne 
National  Laboratory  provided  some  general  observations  on  documentation  standards. 

Participants  in  this  session  agree  that  the  production  of  good  documentation  is  not  an 
incidental  byproduct  of  software  development;  concentrated  effort  must  be  given  to 
achieve  a  useable  result,  one  which  takes  into  account  human  factors  and  the  realities 
of  continued  change. 
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Auditing  Systems  Documentation 


Richard  J.  Thompson 


Manager,  System  Records 
Chemical  Abstracts  Service 


Chemical  Abstracts  Service  was  an  early  proponent  of  and  has  a  continuing 
commitment  to  standards  and  guidelines  for  data  processing  documentation. 
Recently,  the  organization  performed  an  audit  to  assess  the  state  of  health  of 
its  system  documentation  and  to  determine  its  current  effectiveness  in  a  techni- 
cal environment  which  did  not  exist  when  standards  were  first  put  into  effect. 
The  audit  process,  findings  and  analyses  are  presented  as  one  company's  set  of 
experiences.    It  is  hoped  that  these  experiences  will  serve  to  stimulate  others 
in  examining  their  own  systems  documentation  activities. 


1.  INTRODUCTION 


Over  a  period  of  time,  any  system  can  become  less  efficient  as  it  undergoes  internal 
change,  or  takes  incremental  steps  to  track  its  external  environment.    At  some  point,  a 
comprehensive  audit  of  the  current  system  and  its  environment  needs  to  be  performed  to 
gain  a  new  overall  perspective  to  act  as  a  benchmark  for  future  improvements. 


Chemical  Abstracts  Service  (CAS)  introduced  extensive  changes  to  its  system  documen- 
tation practices  in  1972:    A  central  library  was  formed  to  process  and  store  computer 
system  documents  and  to  control  changes  to  system  libraries,  content  and  delivery  require- 
ments were  revised,  and  the  Standards  Committee  was  charged  with  the  review  of  all  new 
documentation  requirements. 

During  the  next  eight  years,  CAS  systems  had  progressed  from  a  batch  environment 
using  a  single,  large-scale  computer  to  a  distributed,  online  data  base  orientation.  The 
central  library  made  similar  technical  advancements  to  modernize  its  internal  processes  in 
capturing  the  increased  volume  and  varied  types  of  system  and  program  documentation.  But 
in  the  transition,  central  library  emphasis  shifted  to  the  operating  level  of  documenta- 
tion (versus  general  system  level)  needed  for  proper  change  control.    At  the  same  time, 
the  role  of  data-oriented  documentation  became  more  active  as  the  needs  for  greater  file 
and  database  integrity  materialized.    Related  database  functions  also  matured  which  added 
new  components  to  overall  system  documentation  in  addition  to  individual  systems  applica- 
tion. 
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Given  these  evolutionary  changes,  CAS  management  requested  an  audit  to  examine  and  assess 
the  present  state  of  EDP  systems  documentation.  Implied  in  this  overall  objective  was  an 
assessment  of  the  following  characteristics  of  system  documentation: 


0    Identity  and  purpose  of  system  documents. 

0    Compliance  of  actual  practice  with  CAS  documentation  standards. 

0    Documentation  quality  in  terms  of  coverage,  accuracy,  currency,  timing,  and 
utility. 

0    Effectiveness  of  documentation  with  respect  to  cost  and  demands  on  the  time  of 
design  and  maintenance  staff. 


2.  BACKGROUND 


2.1    Scope  of  Documentation  Activity 


It's  estimated  that  25  staff  equivalents  are  routinely  involved  in  the  generation  and 
administration  of  CAS  systems  documentation.    The  central  administrative  function  supports 
the  activities  of  150  analysts  and  programmers  as  well  as  operations  and  user  staff.  The 
documentation  inventory  involves  approximately  200  systems,  12,000  modules,  8000  files  and 
3000  data  elements.    The  administrative  system  was  first  established  to  be  a  storage  point 
for  system  documents  and  as  a  focal  point  for  program  change  control.    It  has  since  grown 
to  provide  a  wide  range  of  related  functions  which  include  library  reference  services, 
maintenance  of  program  libraries,  data  base  records,  physical  tape  and  disk  management, 
file  reorganization,  recovery  system  design  and  operation,  archive  management  and  other 
recording  and  consultive  services. 


The  current  cost  of  systems  documentation  at  CAS  is  almost  equally  divided  between 
generation  and  administration  of  records.    The  cost  of  document  administration  has 
incrased  marginally  over  the  years  with  the  addition  of  newly  centralized  functions.  The 
cost  of  document  generation  is  based  on  management's  commitment  to  allocate  10%  of  all 
project  development  work  for  documentation  tasks,  and  thus  will  vary  directly  with  the 
number  of  staff  involved  in  project  activity. 


2.2    Internal  Documentation  Guidelines 


The  CAS  Data  Processing  Standards  and  Procedures  Manual  is  the  major  reference  for 
guiding  the  preparation  and  control  of  documentation.    Documentation  and  other  topics  in 
the  manual  are  regularly  reviewed  by  a  Standards  Committee  composed  of  technical  and 
supervisory  staff. 


In  addition  to  the  Standards  and  Procedures  Manual,  lectures  on  standards  and 
documentation  are  available  on  video  tape  and  are  mandatory  sessions  for  systems  develop- 
ment programmer  trainees.    The  standards  lecture  provides  a  general  orientation  on  the 
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reasons  for  standards  at  CAS,  how  to  use  the  Standards  Manual,  how  to  locate  forms  and 
procedures,  and  an  introduction  to  the  standards  committee  and  Central  Library  activities. 
The  bulk  of  the  documentation  lectures  emphasize  techniques  for  making  comments  on  list- 
ings. 


All  training  programs  are  required  to  be  documented  and  are  regularly  reviewed  by 
Programming  Groupleaders.    Other  documentation  guidance  and  assistance  for  more 
experienced  staff  is  on  an  informal  peer  basis. 


Guidance  is  more  adequately  provided  for  detailed  operating-level  documentation 
(through  training  sessions,  specific  attention  to  forms,  standards  and  procedures  in  the 
manual)  than  it  is  for  general -level  systems  documents.    The  content  of  these 
general -1 evel  documents  (user  requirements,  conceptual  design,  system  summary,  and  user 
manuals)  tends  to  be  flexible  and  thus  reflects  the  general  guidelines  and  suggestions  for 
topic  content  appearing  in  the  manual. 


3.    THE  AUDIT  PROCESS 


3.1    Audit  Scope 


The  documentation  examined  in  the  audit  is  that  associated  with  the  development, 
operation,  maintenance,  and  use  of  CAS  computer  systems.    The  itemized  list  of  specific 
documents  is  lengthy,  but  in  general  it  included  systems  and  program  documents,  data  base 
and  run  documents,  and  user  and  operating  manuals.    Collectively,  these  items  constitute 
the  CAS  systems  documentation  end  product.    Control  type  documentation  was  addressed  only 
to  the  extent  that  it  contributed  to  the  analysis  of  the  documentation  process.  Thus, 
such  items  as  project  management/control  documents,  forms,  logs,  and  transfer  documents 
involved  in  the  process  of  preparing  the  systems  documentation  end  product  were  not 
treated  extensively  in  the  audit. 


3.2    Audit  Staff 


The  audit  team  included  representatives  from  the  systems  development,  operation, 
maintenance,  and  records  areas  of  the  organization. 


Groupleaders  from  the  Systems  Development  and  Research  Departments  were  also  involved 
in  audits  of  individual  systems.  Project  Leaders  reviewed  the  results  of  these  audits  and 
approximately  100  staff  from  18  development,  operating,  and  using  departments  participated 
in  a  survey  of  documentation  usage. 
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3.3    Audit  Method 


Exploratory  work  was  first  conducted  with  R&D  department  and  division  management  and 
an  independent  consultant  to  outline  the  purpose  and  scope  of  the  documentation  audit,  and 
to  develop  and  clarify  sub-objectives.    A  detailed  work  plan  was  generated  as  a  result  of 
these  meetings. 

The  CAS  Data  Processing  Standards  and  Procedures  Manual  was  reviewed  to  identify  the 
items  which  constitute  the  systems  documentation  end  product.    This  step  developed  a 
working  control  list  of  documents  against  which  individual  systems  were  audited. 

Seven  systems  were  audited  for  compliance  against  the  control  list.    Auditors  with 
various  systems  experience  and  perspective  also  reported  on  the  quality,  completeness, 
timeliness,  and  accuracy  of  the  individual  systems.    Results  were  then  discussed  with  the 
relevant  project  leaders.    The  systems  selected  included  in-process  and  production  sys- 
tems, large  and  small,  online  and  batch,  and  other  varying  characteristics  to  provide  a 
reasonable  sample  for  observing  differences  in  documentation  results. 


Two  hundred  survey  questionaires  were  issued  to  staff  in  18  CAS  departments  to  deter- 
mine the  predominant  reasons  for  using  documentation,  the  frequency  of  access  of  various 
documents,  and  the  availability  and  utility  of  systems  documentation  in  general. 


Audit  staff  also  collected  other  pertinent  data  to  describe  the  scope  of  the  documen- 
tation activity  at  CAS,  its  costs,  and  staff  involvement;  to  generate  critiques  of  various 
processes;  and  to  collect  suggestions  for  improvement. 


4.    AUDIT  FINDINGS 


Overall  findings  of  the  1980  documentation  audit  indicate  that  the  current  CAS  system 
of  preparing  and  maintaining  documentation  still  adequately  serves  the  system  development 
and  operations  process.    The  areas  needing  improvement  focus  on  more  prompt  delivery  of 
general  level  documentation  produced  during  system  development  (vis-a-vis  more  specific 
operating  documents).    The  survey  also  revealed  how  documents  are  most  used  by  staff  and, 
therefore,  pointed  the  way  in  which  improvements  should  be  installed  to  gain  the  most 
benefit  in  terms  of  document  utility. 


4.1    Individual  System  Audits 


Documentation  audits  were  conducted  on  seven  CAS  systems.    The  systems  characteris- 
tics varied  as  to  development  and  production  status,  online  and  batch,  370-based  and 
distributed,  long  and  short  development  periods,  and  systems  developed  and  documented  by 
different  R&D  organizational  units. 
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The  audits  revealed  no  documentation  deficiencies  that  were  peculiar  to  a  given  type 
of  system.    Each  system  had  most  of  the  specified  documentation;  but  most  systems  were 
missing  documents  that  the  Standards  Manual  said  should  exist.    (Note:    "missing"  is 
defined  as  not  deposited  in  the  Central  Library). 

The  audits  could  not  determine  why  any  given  system  had  relatively  more  comprehensive 
documentation,  or  more  prompt  delivery  than  another  system.    Highly  visible  projects  with 
high  development  priority  might  be  expected  to  have  more  complete  and  higher  quality 
documentation.    Yet,  the  chances  seem  to  be  even  that  full  documentation  will  or  will  not 
be  delivered.    The  only  conclusive  pattern  is  a  lack  of  consistency  in  controlling  the 
delivery  of  documentation. 


4.2    Documentation  Survey 


4.2.1    Is  Documentation  Used? 


The  survey  found  that  all  the  documents  generated  within  the  development,  operating, 
and  using  range  were  being  used.    It  was  also  found,  not  unexpectedly,  that,  di fferent 
groups  of  people  used  some  documents  more  than  others.    Analysts  and  Managers  mentioned 
the  system  description  and  program  documentation  most  frequently;  programmers  overwhelm- 
ingly favored  the  module  listing  and  Data  Base  Documentation;  and  users  mentioned  user 
manuals  and  the  system  description.    In  the  composite  group  of  94  respondents,  each  of  the 
8  classses  of  documents  received  between  51  (run  doc)  and  70  (DB  doc)  mentions. 


4.2.2     What  is  Documentation  Used  For? 


One  might  expect  that  the  original  purpose  of  having  documentation  at  all  would 
correspond  with  staff's  reasons  for  using  it  now,  and  this  purpose  would  be  to  run  a 
system  or  to  make  changes  to  it.    It  turns  out  that  "changing  the  system"  and  "system 
orientation"  are  the  leading  reasons  (a  tie)  why  staff  use  documentation.    "Operating  the 
system"  fell  behind  (by  60%)  such  choices  as  "designing  new  systems,"  and  "debugging;"  but 
ahead  of  "generating  their  own  documentation." 


Although  the  users  need  documentation  to  operate  the  system  (60%  of  the  respondents 
said  so),  they  also  need  it  for  debugging,  orientation,  changing  the  system,  and  gener- 
ating documentation.    This  interest  indicates  a  larger  scope  of  technical  activity  in  the 
CAS  user  community  than  previously  experienced  due  to  the  rotation  and  migration  of  data 
processing  staff  to  user  groups. 


4.2.3.    Which  Documents  Are  Used  Most  Frequently? 


The  indisputable  answer  to  this  question  is  the  module  listing.    This  is  based  on 
responses  to  the  question,  "How  often  (expressed  in  percentages)  do  you  access  each  of 
these  documents?"    Analysts  and  Managers  use  the  System  Description,  and  then  the  listing 
most  often.    Listings  are  by  far  the  most  accessed  document  for  programming  use.    The  user 
manuals  and  run  documentation  are  the  significant  references  for  users.    Weighted  accesses 
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for  the  composite  population  show  that  the  listing  leads  all  documents  by  a  wide  margin; 
the  remaining  documents  are  in  a  narrow  access  range  with  user  manuals  on  top. 


The  audit  team  noted  that  the  utility  of  the  listing  has  become  more  important  since 
module  documentation  was  recently  incorporated  into  it  via  standard  comments.    This  fea- 
ture is  also  expected  to  improve  the  currency  of  that  documentation. 


4.2.4    Does  Documentation  Satisfy  Needs? 


Given  a  choice  of  "never/usually/always,"  the  predominent  opinion  of  staff  is  that 
documentation  usually  meets  their  needs.    There  were  many  qualified  responses  to  this 
question  ("usually,  but  ...  "),  and  half  the  staff  offered  specific  suggestions  for  adding 
to,  deleting  or  expanding  various  documents.    From  these  and  other  general  comments,  the 
audit  team  interpreted  the  response  as  an  overall  satisfaction  with  the  existing  documen- 
tation, but  that  staff  feel  there  is  a  definite  need  for  improvement. 


Listings  and  data  base  documents  received  the  highest  marks  in  relevancy  for  staff 
needs.    The  system  description,  program  and  module  documentation  received  the  lowest. 
General  comments  reflected  the  opinion  that  there  is  little  confidence  in  the  currency  or 
accuracy  of  this  general  level  documentation. 


At  least  half  the  time,  staff  go  to  some  other  person  for  help  in  answering  their 
questions.    This  occurs  in  cases  where  documentation  can't  be  found,  or  doesn't  address  a 
particular  question.    The  source  most  often  named  was  the  "system  expert,"  then  the 
"user,"  then  the  code  itself.    Programmers  preferred  to  ask  other  programmers  or  refer  to 
the  code,  while  the  "users"  main  source  of  reference  was  a  programmer. 


4.2.5    What  References  Are  Used  in  Preparing  Documentation? 


None  of  the  respondents  relied  on  any  single  source  of  help  in  generating  their  own 
documentation.    Analysts  and  Managers  and  Programmers  most  often  used  the  Standards  Manual 
and  existing  system  documentation  for  help;  Users  relied  on  other  documentation  and  peers. 
In  the  composite  sample,  references  were  cited  in  the  following  order:    other  documenta- 
tion, Standards  Manual,  peers,  supervisor,  no  help  needed  (even  these  respondents  checked 
a  second  source  -  usually  the  Standards  Manual  or  other  documentation),  and  training 
classes. 


4.3    User  Documentation 


In  conducting  the  audit,  team  members  expected  more  vocal  complaints  about  user 
documentation  than  were  actually  received  from  users.    But,  users  sided  with  other  staff 
in  expressing  major  concern  with  the  currency  of  other  documentation  as  well  as  user  doc. 


Audit  results  were  revealing  in  that  users  have  the  same  functional  reasons  and 
access  the  full  range  of  documents  much  as  their  analyst  and  programmer  counterparts  do. 
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This  reflects  a  greater  degree  of  staff  experience  and  more  project  participation  and 
which  in  turn  indicates  a  larger  scope  of  technical  activity  than  expected  in  the  CAS  user 
community. 


In  addition  to  the  several  systems  cited  for  which  user  documentation  is 
non-existent,  User's  prime  concerns  were  as  follows: 

0  More  detail  is  needed,  completeness  of  run  documentation  and  flow  charts. 

0  The  need  for  more  user-oriented  documentation  and  less  computer  jargon. 

0  Better  coordination  of  changes. 

0  Identification  of  document  authors  and  purpose  of  changes. 
0  Better  documentation  of  computer  reports. 
0  Removal  of  redundant  or  useless  data. 


5.    ANALYSIS  AND  RECOMMENDATIONS 


The  recommendations  of  the  audit  team  dealt  directly  with  ensuring  an  improved  level 
of  currency  of  system  documentation.    It  was  recognized  that  the  currency  problem  had  many 
attributes.    Documentation  could  be  missing  (from  the  Central  Library),  incomplete,  lost, 
late  and/or  inconsistently  revised. 


In  fact,  one  of  the  major  symptoms  of  poor  currency  observed  in  the  audits  was  that 
detailed  operating  and  data  base  level  documents  were  not  consistently  reflected  in  the 
more  general  systems  and  program  documents.    As  a  result,  programs  and  data  sets  currently 
in  use  for  a  system  were  reflected  in  operating  level  documents  but  were  not  identified  in 
the  system.    There  were  also  instances  where  system  A  used  copy  code  from  system  B  and  was 
unaware  of  subsequent  changes  to  system  B.    Some  detailed  changes  were  observed  which 
altered  the  logic  of  a  program  or  function  of  a  system,  but  documentation  was  not  revised. 


Specific  recommendations  were  made  to  correct  several  administrative  and  control 
faults  which  contributed  to  the  currency  problem. 


5.1    A  Separate  Documentation  Manual 


The  CAS  Data  Processing  Standards  and  Procedures  Manual  is  a  major  reference  source 
for  guiding  the  preparation  and  control  of  documentation.    Documentation  gets  extensive 
treatment  in  the  Manual,  but  specific  procedures  are  scattered  and  imbedded  in  other 
dominant  topics.    Given  the  level  of  indexing  and  cross-referencing  in  the  manual,  it 
becomes  necessary  to  leaf  through  the  Manual  for  a  thorough  and  complete  understanding  of 
the  subject.    There  are  also  many  ambiguities  in  delivery  requirements,  document  intent, 
audience,  and  responsibility  for  preparation. 
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A  separate  manual  has  been  proposed  for  comprehensive  treatment  of  the  whole  spectrum 
of  documentation  activity.    This  will  sharpen  the  focus  on  the  topic,  become  a  single 
authoritative  guide  for  training,  and  an  ongoing  reference. 


5.2    Standardized  Composition  and  Terminology 


Elementary  controls  are  being  established  which  will  eliminate  problems  caused  by 
inconsistent  use  of  terminology  and  document  composition.    For  example,  system  documents 
delivered  to  a  central  function  may  use  different  titles.    Further,  they  may  be  packaged 
in  notebooks  with  still  different  labels.    As  a  result,  documents  sometimes  cannot  be 
recognized  for  what  they  are.    Positive  statements  will  be  used  in  following  outlines, 
since  it  can't  be  determined  if  gaps  in  documents  are  a  result  of  omission  or  commission. 
Other  composition  faults  include  the  lack  of  dates  or  author  names;  missing  tables  of 
contents,  bibliographies,  and  reference  lists;  shortcut  methods  (e.g.  "see  REFAID")  which 
are  not  explained;  and  forward  references  (e.g.  "see  (other)  Program  X  for  halt  log") 
which  may  not  exist  or  may  have  been  changed  independently. 


5.3    Unified  System  Document 


A  system's  documentation  becomes  fragmented  when  there  is  no  single  storage  point 
which  collects  all  the  information  on  a  system  and  when  existing  documents  are  organized 
for  ease  in  internal  use  or  for  individual  department  convenience.    The  Central  Library 
itself  will  file  module  listings,  program  documentation,  run  documentation,  data  elements, 
run  procedures,  etc.  in  different  areas.    Pertinent  system  memos  and  reports  may  exist  in 
other  department  files.    Detailed  run  documentation,  data  set  definitions,  and  file 
recovery  procedures  are  processed  and  stored  in  still  other  organizational  units. 


This  may  not  be  a  major  cause  for  concern  with  knowledgeable  staff  available  in-house 
who  know  what  to  expect  in  systems  documents  and  where  to  go  to  find  the  missing  pieces. 
However,  it  becomes  a  significant  problem  when  it  is  necessary  to  transfer  all  written 
systems  knowledge  out  of  house  to  colleagues,  archives,  or  users.    With  each  occurrence, 
there  is  a  non-trivial  amount  of  staff  time  expended  to:    1)    identify  what  belongs  to  the 
system,    2)    where  to  cut  off  the  successive  system/program  dependencies,  and    3)  collect 
the  information. 


To  correct  this  situation,  CAS  is  reviewing  its  document  delivery  criteria  for  sys- 
tems development  and  will  emphasize  the  use  of  a  single  systems  notebook  which  will 
include  an  inventory  checklist  of  related  documents,  consistent  use  of  bibliographies, 
standard  nomenclature,  and  references. 


5.4    Document  Delivery  Controls 


General  level  documents  generated  during  the  system  development  process  are  typically 
delivered  much  later  than  system  installation.    Operating  level  documentation  (data  base 
and  run  documentation)  is  normally  current  because  of  its  forms-driven  processing,  produc- 
tion involvement,  and  machine  level  control.    The  central  Library  may  merely  accept  and 
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file  documents  that  are  delivered  without  any  attempt  to  determine  or  enforce  what  should 
be  delivered.    Any  of  these  factors  prevent  the  Library  from  guaranteeing  any  level  of 
integrity  of  system  documentation. 


CAS  plans  to  continue  to  enforce  documentation  requirements  for  production  software 
changes.    Unless  proper  documentation  is  submitted,  the  job  will  not  run:    there  is  no 
appeal.    Periodic  audits  for  missing  documentation  will  also  continue.    A  standardized 
form  of  documentation  checklist  will  be  reviewed  by  Project  Leaders  and  Managers  for 
individual  applications  systems.    The  checklist  will  be  used  by  the  library  to  determine 
what  documents  should  be  delivered.    A  collection  of  checklists  will  form  the  basis  for 
total  inventory  of  CAS  systems  documents. 


5.5    Document  Trace  Procedure 


To  some  extent,  the  overall  documentation  environment  will  continue  to  be  fragmented, 
and  staff  will  still  rely  on  their  experience  and  knowledge  of  what  data  base  reference 
aids  exist  or  what  information  is  contained  in  listings  and  program  libraries.    The  audit 
team  has  proposed  a  written  guideline  which  prescribes  how  to  identify,  trace.,  and  collect 
the  pertinent  documents  of  a  system.    The  trace  procedure  will  describe  common  procedures 
of  document  administration  and  specify  (e.g.)  how  to  identify  modules  called  by  other 
modules,  what  Data  Base  or  general  purpose  utilities  are  needed  to  run  the  system  in 
question,  where  to  find  and  how  to  use  inventory  lists  and  references  which  are  located 
in  other  physical  areas. 


6.    MANAGEMENT  ENVIRONMENT 


A  final  point  worth  mentioning  is  that  no  documentation  function  can  ever  expect  even 
a  near  perfect  document  compliance  and  currency  environment  without  strong  management 
support.    CAS  is  continuing  its  commitment  to  quality  documentation  by  implementing  the 
recommendations  proposed  in  the  audit  and  incorporating  them  with  the  results  of  a  paral- 
lel effort  to  review  and  analyze  the  systems  development  methodology  and  its  deliverable 
documents. 


CAS  expects  that  in  implementing  these  improvements,  it  will  be  in  a  better  position 
to  support  such  new  advances  in  its  technical  environment  as  Programmers  Workbench, 
UNIX-based  systems,  office  automation  and  electronic  transfer  of  information. 
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Use  of  the  Users  Manual  as  a  Quality  Control  Tool 
Carol ine  S.  Levenson 
Edition,  Inc. 

The  preparation  of  user  documentation  should  be  viewed  as  a  quality 
control  task.    In  this  task,  a  documentation  specialist  reviews  the 
developed  system,  its  user  interfaces,  and  operatinq  procedures  to 
verify  that  all  functions  are  integrated  oroperly  and  that  user  reauire- 
ments  have  been  met.    However,  to  serve  as  a  quality  control  vehicle, 
the  Users  Manual  standards  prescribed  by  FIPS  PUB  38  must  be  modified 
to  stress  the  user's  information  needs  rather  than  the  system's  internal 
components. 

Keywords:    Quality  control;  Quality  control  tool;  Users  Manual;  System 
Verification,  User  information. 

1.  INTRODUCTION 

Computer  documentation  is  usually  the  last  task  to  be  performed  in  a  system 
development  effort.    While  this  is  not  ideal,  it  is  a  very  real  situation  and  can  be  used 
to  advantage  if  the  documentation  orocess  is  used  as  a  nualitv  assurance  or  control  task. 

This  paper  discusses  how  the  Users  Manual  in  Federal  Information  Processing 
Standards  (FIPS)  Publication  38  (FIPS  PUB  38)  [1]  could  be  used,  with  some  modifications, 
as  a  guideline  for  this  tvpe  of  auality  control.    In  this  discussion,  the  current  Users 
Manual  contents  are  evaluated*    and  changes  are  sugaested. 

2.  RECOMMENDATIONS 

The  following  are  recommendations  for  changes  to  the  current  Guidelines  for  user 
documentation: 

1.  One  or  more  Users  Manuals  should  be  prepared  for  any  new  system  to  describe 
the  overall  use  and  intent  of  the  system  and  its  products  as  well  as  all 
system  interfaces  and  reauired  procedures.    Regardless  of  size,  any  system 
is  a  failure  if  its  user(s)  can  not  understand  and  effectively  work  with 

it  and  its  data  products. 

2.  The  Users  Manual  should  not  be  a  restatement  or  cooy  of  information  presented 
in  previous  documents  (e.g.,  Reouirements  and  Specifications)  in  the  system 
life  cycle. 

3.  A  documentation  special ist(s)  who  has  not  been  responsible  for  hands-on 
development  work  should  be  assigned  the  task  of  preparing  the  Users  Manual(s) 
This  person  should  be  free  of  the  assumptions  and  built-in  oartiality  that 
exist  for  members  of  the  development  team  and,  thus,  could  review  the  svstem 
from  a  ouality  control  perspective. 

4.  In  developing  user  documentation,  the  documentation  specialist  nerforms  a 
quality  control  function  by  verifying  that  the  user's  reouirements  were 
fulfilled  by  the  developed  system  and  that  the  procedures  (e.g.,  data  entry, 
report  analysis,  and  operations)  for  user  interaction  are  correct  and  can  be 
carried  out  efficiently  by  the  designated  user  renresentati ves .    This  veri- 
fication process  should  be  thorough  to  be  meaningful  and  may  entail  a  wide 
variety  of  activities,  such  as  (1)  interviews  with  the  user  to  review  expecta 
tions  and  requirements  and  to  determine  the  availability  and  skill  levels  of 
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persons  who  will  interface  with  the  svstem  and  (2)  detailed  wal k-throughs  of  the 
procedures  with  existing  test  data  or  other  specially  prepared  data. 

3.    THE  QUALITY  CONTROL  FUNCTION 

3.1  General 

Documentation  is  currently  considered  a  reoortina  task  in  which  the  development 
team  passes  along  the  information  it  has  gained  durino  the  system  life  cycle.    The  drawback 
to  this  involvement  in  both  development  and  documentation  is  that  the  develooment  team  is 
usually  too  familiar  with  the  system  and  can  not  divorce  itself  from  a  development  per- 
spective.   Also,  a  conflict  of  interest  could  arise  if  accented  svstem  specifications  are 
found  to  have  incorrectly  translated  user  reauirements  or  were  not  undated  with  channes  in 
those    reauirements.    Conseauentl y ,  the  development  team  can  not  review  what  it  has  done 
with  impartiality  for  documentation  or  ouality  control  purposes.    This  is  especially  true 
with  user  documentation,  which  would  require  the  development  team  to  steo  out  of  its 
natural  role  and  "think  like  a  user." 

Documentation  can  and  should  be  more  than  a  recordina  of  the  development  team's  work 
to  date.    It  should  be  a  final  aooraisal  of  the  completed  product  and  a  description  of  how 
it  fulfills  all  of  the  user's  requirements,  as  well  as  a  description  of  the  internal  system. 
It  also  should  be  prepared  by  a  documentation  specialist,  who,  like  his  counterpart  in 
industry,  is  "outside"  of  the  development  team  and  checks  the  svstem  to  verify  that  expected 
capabilities,  functions,  and  characteristics  do  indeed  exist.    This  check  can  be  as 
straightforward  as  comparing  the  developed  svstem  against  Reauirements  Documents  and 
System  Specifications  or  as  extensive  as  performing  a  series  of  wal k-throuahs  of  developed 
system  procedures,  interfaces,  and  products.    In  the  latter  of  the  two  efforts,  the 
documentation  specialist  is  transformed  into  a  mock  user  and  simulates  the  "live"  situa- 
tions and  problems  with  which  the  ultimate  user    and  svstem  must  cope. 

As  discussed  by  the  General  Accounting  Office  (RAO)  in  a  report  to  Connress  on  the 
problems  of  computer  software  development  contracts  [2],  systems  are  often  designed  and 
developed  hastily  with  inadequate  or  no  testing  and  documentation.    This  leads  to  the 
unfortunate  result  that  the  users,  who  most  often  are  the  ones  paying  for  the  development 
effort,  are  left  with  inadeauate  systems  or  systems  that  they  can  not  or  do  not  know  how  to 
use.    Modification  of  the  Users  Manual  guidelines  and  the  use  of  a  documentation  specialist 
to  perform  the  quality  control  function  should  improve  the  quality  and  usability  of 
developed  systems  and  reduce  the  development  team's  post-implementation  level  of  effort. 

3.2  Documentation/Quality  Control  Tasks 

The  main  activities  of  the  documentation  specialist  in  preparing  user  documentation 
and  performing  quality  control  should  be  to: 

t       Review  existing  documentation  (e.g..  Functional  Reauirements  Document  and 
System/Subsystem  Specifications). 

•  Interview  all  user  groups  that  will  interface  with  the  system  plus  selected 
development  team  members  (as  necessary). 

•  Review  all  svstem  output  for  desired  format,  usability,  and  data  auality. 

t       Check  program  code  as  necessary  to  obtain  suDoorting  information,  such  as 
calculations  performed,  validation  criteria,  error  messages,  and  general 
processing  characteristics. 

•  Prepare  procedures  for  user  interface  points,  including  at  least  data 
preparation  (completion  of  input  forms),  data  entry,  error  correction,  output 
distribution,  and  output  analysis. 
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A11  of  the  above  activities  are  necessary  for  good  user  documentation,  because  thev 
look  at  system  aspects  that  are  visible  to  the  user.    In  order  to  evaluate  procedures  that 
have  been  developed  for  the  user,  the  documentation  specialist  must  identify  with  the  user, 
not  the  development  team,  and  perform  all  involved  steps.    In  so  doing,  he  is  the  original 
integrator  of  the  entire  processing  scheme  and  can  decide  whether  or  not  all  user 
requirements  have  been  satisfied. 

4.     USE  OF  USERS  MANUAL  AS  DUALITY  CONTROL  TOOL 

4.1  Scope 

The  prescribed  Users  Manual  in  FIPS  PUB  38  contains  detailed  information  on  the 
system  software  so  "the  user  organization  can  determine  its  applicability  and  when  and 
how  to  use  it."    This  quotation  from  FIPS  PUB  38  points  out  the  main  difficulty  with  the 
Users  Manual  standards  both  in  terms  of  educatina  the  user  and  in  performing  system 
qual ity  control . 

The  goal  of  the  Users  Manual  should  be  to  show  the  user  how  the  system  is  applied, 
including  when  and  how,  rather  than  providing  him  with  the  information  from  which  the 
when  and  how  can  be  derived.    This  information  is  aathered  and  verified  by  the  documentation 
specialist  from  his  detailed  review  of  the  system  and  all  developed  user  procedures. 

The  Users  Manual  should  be  an  outgrowth,  not  a  repeat,  of  the  Functional  Requirements 
Document.    However,  parts  of  this  document  often  are  copied  and  transferred  to  the  Users 
Manual  without  review  or  verification.    Also,  one  Users  Manual  usually  is  not  sufficient  to 
cover  all  unique  user  groups  and  their  information  requirements  and  procedures  in  detail. 
A  separate  Users  Manual  should  be  prepared  for  each  major  interface  point/user  group  or  set 
of  unique  procedures.    However,  the  FIPS  PUB  38  Users  Manual  as  it  now  stands  is  a  general 
management  overview  instead  of  an  individualized  document  for  different  user  groups. 

Each  user  group  must  understand  its  specific  role  in  the  processing  scheme  and  must 
be  given  detailed  instructions  to  follow  or  the  entire  system,  though  perhaps  100  percent 
code  perfect  and  efficient,  will  not  succeed.    User  ignorance,  distrust,  and  misunderstand- 
ing are  definite  causes  of  many  system  failures  and  must  be  circumvented  by  improved  user 
documentation. 

The  following  paragraph  describes  the  FIPS  PUB  38  Users  Manual  and  discusses  what 
changes  are  necessary  to  better  address  user  needs  and  serve  as  a  guideline  for  quality 
control  of  the  system.    Tables  1  and  2  should  be  reviewed  in  conjunction  with  this 
discussion,  because  they  show  the  current  content  outline  for  the  Users  Manual  and  compare 
the  current  guidelines  with  proposed  changes. 

4.2  Review  of  Users  Manual  Sections 

4.2.1     General  Information  Section 

The  first  section  of  the  Users  Manual  is  a  synopsis  of  the  system  and  its  applica- 
tion by  the  user.    Unfortunately,  the  prescribed  contents  do  not  emphasize  the  crucial 
difference  between  this  and  the  general  information  sections  in  other  FIPS  PUB  38  documents 
and  specifications. 

Because  of  this  similarity,  this  section  is  often  copied  from  other  existing 
development  documents,  even  though  the  intent  of  this  manual  should  be  user-  rather  than 
development-oriented.    This  section  should  tell  the  user  why  the  system  exists  and  why  he 
needs  it  as  well  as  how  the  system  will  helo  him  to  do  his  job  better.    This  is  far 
different  from  simoly  summarizing  the  "application  and  general  functions  of  the  system"  as 
is  prescribed  in  FIPS  PUB  38. 
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TABLE  1 


FIPS  PUB  38  Users  Manual  Contents 


SECTION  1.    GENERAL  INFORMATION 

1.1.  Summary 

1.2.  Environment 

1.3.  References 

SECTION  2.  APPLICATION 

2.1.  Description 

2.2.  Operation 

2.3.  Equipment 

2.4.  Structure 

2.5.  Performance 

2.6.  Data  Base 

2.7.  Inputs,  Processing,  and  Outputs 
SECTION  3.     PROCEDURES  AND  REQUIREMENTS 

3.1.  Initiation 

3.2.  Input 

3.2.1.  Input  Formats 

3.2.2.  Sample  Inputs 

3.3.  Output 

3.3.1.  Output  Formats 

3.3.2.  Sample  Outputs 

3.4.  Error  and  Recovery 

3.5.  File  Query 


Comparison  of  Current  and  Proposed  User  Manual  Guidelines 


TABLE  2 


CURRENT  GUIDELINES 


PROPOSED  GUIDELINES 


1.    GENERAL  INFORMATION 


1.1 


S  umma  ry 


Summarize  application  and  general  function 
of  software. 


Summarize  information  needs  solved  by  system 
and  describe  user  interfaces  and  uses  of 
system  products. 


1.2 


Environment 


Identify  user  organization  and  computer 
center  where  software  is  installed. 


Identify  user  organizations  and  eauipment 
used  in  system  interaction;  also  summarize 
computer  capability,  location,  and  availability, 
as  well  as  contacts  for  solving  equipment  and 
related  problems. 
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TABLE  2 

ComDarison  of  Current  and  Prooosed  User  Manual  Guidelines  (Continued) 

CURRENT  GUIDELINES  PROPOSED  GUIDELINES 

1.3.  References 

List  of  project  authorization,  existing  Same  content  as  current  guidelines, 

project  documentation  and  reference  docu- 
mentation, and  FIPS  oubl ications . 

2.  APPLICATION 


2.1. 

Description  of  when  and  how  software  is  used 
and  unique  support  provided  to  user  organi- 
zation, including  purpose  of  software, 
capabilities  and  operating  improvements 
provided,  and  functions  performed. 

2.2. 

Description  of  operating  relationships  of 
functions  described  in  Paragraph  2.1.  Also, 
security  and  privacy  considerations  and  flow 
charts  or  descriptions  of  input/outout  are 
provided  here. 

2.3. 

Description  of  equipment  on  which  software 
can  be  run. 


2.4. 

Show  software  structure  and  describe  role  of 
each  component  in  operation  of  software. 


2.5. 

Describe  performance  capabilities  of  soft- 
ware, including  quantity  of  input/output, 
response  time,  processing  time,  error  rates, 
and  qualitative  information  about  flexi- 
bility and  reliability. 


2.6, 


Descri  ntion 

Same  content  as  current  guidelines,  except  for 
more  emphasis  on  user  information  needs  rather 
than  software.    Also,  an  Application  section 
should  be  prepared  to  address  each  specific 
user  group  separately  in  different  manuals. 

Operation 

This  area  should  be  renamed  "User  Interface" 
to  describe  input/output  interfaces  rather 
than  software  functions  and  processing.  As 
with  all  Apolication  section  paragraphs,  it 
should  address  each  user  grouo  individually. 

Equipment 

Overview  of  the  equipment  used  by  the  user 
in  interfacing  with  the  system  as  well  as 
detailed  instructions  on  use  of  this  equipment. 

Structure 

If  this  area  is  to  be  included  in  the  Manual, 
it  should  be  put  at  the  end  of  the  manual, 
since  it  is  system-oriented  information. 

Performance 

Description  of  interface  work  cycle,  starting 
with  initiation  of  data  through  analysis  and 
use  of  data  products.    Also  schedules  for 
work  cycle  stages.    Ideallv,  this  area  should 
be  a  subset  of  2.2,    Operation.  However, 
system-oriented  information,  such  as  that 
covered  by  ctirrent  Guidelines  can  be  imnortant 
and  could  be  included  in  one  system-oriented 
section  at  the  end  of  the  manual. 

Data  Base 


Description  of  data  files  being  used  by  Same  as  current  guidelines,  but  including 

system  and  the  purpose  of  each  file.  information  on  update,  backup,  and  other 

functions  related  by  the  data  base.  This 
section  should  be  at  the  end  of  the  manual 
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TABLE  2 

Comparison  of  Current  and  Proposed  User  Manual  Guidelines  (Continued) 

CURRENT  GUIDELINES  PROPOSED  f^UIDELINES 

2,7.    Inputs,  Processing,  and  Outputs 

Description  of  inputs,  flow  of  data  through  This  area  should  be  eliminated,  since  2.2, 
processing  cycle,  and  resultant  outputs.  Operation,  should  include  this  information. 

Also  relationships  among  inputs  and  outputs. 

3.  PROCEDURES  AND  REQUIREMENTS 


3.1. 

Description  of  step-by-step  procedures  used 
to  initiate  processing. 


3.2. 

Definition  of  requirements  for  preparing 
input  data  and  parameters . 


3.3. 

Definition  of  reauirements  relevant  to 
each  output. 


3.4. 

List  of  error  codes  or  conditions  nenerated 
by  software  and  corrective  action  taken  by 
user. 


3.5 

Detailed  instructions  for  initiating, 
preparing,  and  processing  query  of  data 
base  wherever  applicable.  Also  instructions 
for  use  of  terminal  if  necessary. 


Initiation 

Description  of  actual  completion  of  any  source 
documents,  including  both  data  content  and 
coding  and  processing  flow. 

Input 

Since  3.1,  Initiation,  covers  the  preparation 
of  the  input  data,  this  area  should  cover  the 
actual  procedures  for  data  entry.    These  pro- 
cedures must  be  step-by-step  details  of  what 
the  user  must  do  to  enter  data  and  what  the 
system  will  respond  with,  if  applicable.  If 
error  correction  is  not  elaborate,  it  should 
be  included  in  this  area  instead  of  3.4, 
Error  and  Recovery. 

Output 

Same  content  as  current  guidelines,  but  with 
emphasis  on  analysis  of  data  content  and  use 
of  data. 

Error  and  Recovery 

This  area  should  follow  3.2,  Input,  immediately 
or,  in  the  case  of  basic  correction  of  input 
data,  should  be  included  in  3.2.    The  content 
is  similar  to  the  current  guidelines,  but 
emphasizes  procedures  for  error  correction 
and  recovery  before  listing  error  codes  and 
detailed  corrective  actions. 

File  Query 

Same  content  as  current  guidelines,  but 
instructions  for  use  of  terminal  should 
have  been  described  in  the  Input  area.  Thus, 
the  content  should  reference  basic  instructions 
in  that  area  while  stressing  only  ouery-related 
instructions  here. 
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The  following  bulleted  items  describe  suggested  chanaes  in  terms  of  the  major 
questions  that  a  user  wants  answered  in  this  section. 

•  Why.    This  should  be  answered  by  1.1,  Summary.    It  should  tell  why  the 
system  is  being  developed,  which,  generally,  is  to  help  the  user  to  do  his 
job  faster  and  more  efficiently  or  productively. 

•  How.    This  should  be  a  description  of  the  major  functions  and  caoabilities  of 
the  system  dIus  a  reiteration  of  the  authorizina  publications  or  documents  in 
1.3,  References.    However,  to  eliminate  the  need  for  uodatina  due  to  changes  in 
the  documents  covered  in  1.3,  references  to,  rather  than  summaries  of,  such 
documents  would  be  preferable. 

•  When  and  Where.    These  questions  should  be  answered  by  1.2,  Environment,  which 
should  be  more  than  an  identification  of  user  groups  and  the  comouter  center. 
It  should  provide  the  timeframe  (e.g.,  quarterly,  monthly)  of  a  processing 
cycle  and  pinpoint  the  individual  user  groups  involved  in  the  function  or 
interaction  being  documented. 

This  section  should  also  describe  the  major  user  interface  points  in  general 
terms  and  describe  how  these  interfaces  are  achieved  (e.g.,  online  terminals, 
batch  processing,  and  remote  printout  and  delivery). 

4.2.2  Application 

This  section  presents  an  overview  of  how  the  system  is  used.    Currently,  it  combines 
all  user  groups  into  one  composite  user  and  tries  to  describe  the  duties  and  processing 
schedules  of  this  fictitious  user. 

The  Application  section  should  be  divided  into  separate  sections  with  appropriate 
information  for  each  user  grouo  mentioned  in  the  General  Information  Section  (as  revised). 
Or,  if  user  groups  are  distinct  enough  and  the  interaction  procedures  warrant  it,  each  user 
group  should  be  addressed  in  a  separate  manual  entirely.    If  the  FIPS  PUB  38  standards  were 
changed  to  prescribe  one  Users  Manual  for  each  distinct  group,  such  as  the  day  shift  of  a 
keyounch  division  or  the  budget  analysts  within  an  accounting  department,  this  section 
would  address  each  subaroup  within  the  major  user  group. 

Other  recommended  changes  for  this  section  are  described  in  the  following  bulleted 

i  terns . 

t       Section  2.2,  Operation.    This  subsection  of  the  Users  Manual  should  be  renamed 
"User  Interaction"  (or  "User  Interface"),  because  it  should  describe  the  input 
and  output  interfaces  rather  than  the  operation  of  the  software.    The  user, 
after  all,  is  most  concerned  with  what  he  must  give  the  svstem  and  what  he 
gets  back  from  it  (and  other  users).    He  is  secondarily  interested  in  how  the 
system  functions  in  receiving  and  producing  data. 

A  graphic  illustration  of  the  user  processes  providing  the  innut  and  the 
system  and  related  processes  producing  the  output  would  be  very  useful  here. 
In  addition,  expected  quantities,  timeframe,  and  a  description  of  the  normal 
processing  cycle  are  very  important  to  the  user  and  should  be  included  in 
this  section. 

®       Section  2.3,  Equipment.    The  equipment  used  by  the  user  may  include  online 

terminals  or  require  the  establishment  of  procedures  for  interaction  with  the 
equipment.    These  should  be  outlined  here  and  detailed  in  Section  3,  Procedures 
and  Requirements.    For  example,  users  may  never  have  used  online  terminals 
before  and  the  Users  Manual  must  tell  them  how  to  do  so  as  well  as  how  to  work 
with  the  application  software.    It  also  must  tell  the  user  about  equipment- 
related  considerations,  such  as  who  to  call  if  equipment  fails  or  if  the 
application  software  is  "down."    Indeed,  it  should  help  the  user  become 
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knowledgeable  enough  to  resolve  minor  eouipment  problems  himself  and  to  at  least 
try    to  determine  whether  a  oroblem  is  software  or  hardware  caused.    This  is 
very  important  to  making  the  user  independent  of  the  development  team  and  con- 
fident that  he  knows  somethino  about  his  system  and  equipment. 

•  Section  2.4,  Structure.    This  section  should  be  placed  adiacent  to  Sections 
2.6  and  2.7,  since  they  all  relate  to  system  functions  and  renui rements .  (How- 
ever, if  proposed  chanqes  to  2.7  are  accepted,  that  section  will  no  longer 
exist. ) 

4.2.3     Procedures  and  Reoui rements 

This  section  presents  information  about  "initation  procedures  and  preparation  of 
data  and  parameter  inputs  for  the  software."    This  is  reasonable,  but  it  does  not  take 
the  user  far  enough.    The  user  needs  to  know  how  to  initiate  processina  (includino  creatine 
source  documents  and  entering  data  into  the  system),  but  also  needs  to  know  how  to  analyze 
any  system  feedback  (such  as  errors  and  general  system-related  information)  and  how  to 
understand  his  output.    Although  these  items  are  covered  in  the  bodv  of  the  section, 
their  lack  in  the  overview  points  out  again  the  need  for  makina  the  Users  Manual  more 
user-ori  ented . 

Specific  changes  suggested  for  this  section  are  described  in  the  following  bulleted 

items : 

•  Section  3.1,  Initiation.    The  majority  of  this  section  should  follow  the 
discussion  of  system  input  (Section  3.2).    However,  an  overview  of  the  aeneral 
processing  flow,  such  as  a  flow  chart  or  other  visual  depiction,  plus  a  brief 
narrative  should  be  left  here. 

f       Section  3.3,  Output.    The  main  change  to  this  section  is  the  need  to  emphasize 
how  the  output  data  is  used.    For  instance,  Section  3.3.2.C  describes  some 
characteristics  of  the  sample  report,  but  it  does  not  describe  any  inter- 
relationships of  reports  or  the  use  of  calculations  or  formulae  in  oroducina 
the  data  values.    Also,  the  definition  of  the  sample  report  does  not  stress  the 
overall  meaning  and  use  of  the  output,  which  is  very  important  when  many  types 
of  outputs  are  being  produced  for  the  same  user.    Also,  output  formats  (3.3.1) 
without  meaningful  data  are  useless.    The  definition  of  output  contents  and 
format  should  accompany  the  sample  reports. 

•  New  Sections.    An  additional  section  is  needed  to  describe  computer-related 
capabilities  or  requirements  associated  with  the  input  and  output  of  the 
system  or  the  user's  interaction  with  the  system.    Examples  are  the  procedures 
for  obtaining  general  system  information  (e.g.,  system  messages  and  processing 
queue  information),   maintaining  a  logging  system  for  input,  and  distribution 
of  output  to  the  user. 

Also,  appendices  of  error  messages  and  correction  procedures  and  data  code 
tables  should  be  included  in  the  Users  Manual.    A  glossary,  wherever  possible, 
would  also  be  helpful  to  the  user. 

NOTE:    If  the  appendix  approach  to  providina  error  messages  and  correction 

procedures  is  used,  it  should  be  for  situations  where  the  number  of  error 
codes  is  voluminous  and  would  be  too  bulkv  to  include  in  the  middle  of 
the  manual  in  Section  3.4. 

5.  SUMMARY 

Although  the  current  FIPS  PUB  38  ouidelines  prescribe  a  Users  Manual  with  a  great 
deal  of  information,  they  do  not  provide  it  in  a  manner  that  is  appropriate  for  the  system 
user.     Indeed,  much  of  the  information  itself  is  about  the  workings  of  the  system  rather 
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than  how  the  user  can  work  with  the  system.    Therefore,  the  current  guidel ines  need  to  be 
rewritten  to  cater  to  the  user's  information  needs.    Bv  imorovina  the  aualitv  of  information 
that  is  supplied  to  the  end  user,  a  revamped  set  of  Guidelines  should  increase  the  usability 
of  systems  and  thereby  ensure  that  the  user  nets  what  he  pays  for. 

The  prenaration  of  the  Users  flanual  is  a  task  best  suited  to  an  individual  who  is 
not  responsible  for  developina  any  part  of  the  system  to  be  documented.    This  individual  is 
the  documentation  specialist,  who  must  identify  with  the  user  and  be  able  to  document  all 
procedures,  however  small,  that  must  be  performed  by  the  user  in  interactina  with  the  system 
In  documenting  these  procedures,  the  documentation  specialist  must  simulate  the  user 
environment  and  thoroughly  check  each  procedure  to  ensure  that  it  as  well  as  the  system  has 
been  developed  properly  and  answers  the  user's  stated  needs. 

The  assignment  of  the  documentation  soecialist  to  the  task  of  preparing  the  Users 
Manual  enables  the  documentation  orocess  to  become  more  than  a  recording  of  facts  and 
procedures.    It  enables  the  process  to  serve  as  a  Quality  control  on  the  system,  user 
interfaces,  and  procedures.    This  quality  control  effort  has  not  been  adequately  addressed 
by  the  data  processing  community.    However,  the  marriage  of  the  user  documentation  and  auali 
control  efforts  into  a  single  task  makes  this  function  more  feasible,    while  increasing  the 
accuracy  of  the  documentation  itself. 


6. 
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ABSTRACT 

The  needs  of  post-design  software  life  cycle  phases  are  not 
met  by  present  requirements  documentation,  and  It  is 
suspected  that  large  economic  losses  are  thereby  being 
incurred.  Requirements  documentation  Is  not  being  kept 
current.  It  is  frequently  too  detailed,  and  the  format 
Inhibits  use  by  the  management  levels  that  most  need  It  In 
the  later  phases.  To  overcome  these  obstacles,  a 
hierarchical  structure  for  software  requirements 
documentation  is  proposed  that  (a)  limits  the  size  of  each 
volume  so  that  It  can  be  easily  handled  and  read,  (b) 
addresses  specific  Information  needs  at  each  management 
level,  and  (c)  Is  easily  maintained.  The  hierarchical 
documentation  Is  supplemented  by  a  single  volume  that 
contains  general  project  Information.  Both  the  structure 
and  the  content  of  suitable  documentation  are  described. 

Key  Words:  Requirements  documentation,  software  management,  software 
maintenance,  software  requirements. 


1.  INTRODUCTION 

In  the  course  of  a  survey  of  software  tool  usage  conducted  for  the  National  Bureau  of 
Standards,  software  developers  were  asked  the  question  "What  are  the  major  software  problems 
In  your  environment?"  Of  17  Individual  problems  Identified  In  response  to  this  question, 
the  largest  number,  seven  related  to  requirements,  and  the  next  highest  category  was 
maintenance  for  which  four  problems  were  mentioned  CHECH813.  The  participants  Involved  In 
this  survey  were  too  few  to  permit  very  conclusive  statements  to  be  formulated.  However,  It 
must  be  surmised  that  requirements  and  maintenance  together  (and  these  are  related,  as  will 
be  shown)  are  Indeed  high  on  the  list  of  problems  that  beset  the  software  community. 

The  detailed  complaints  voiced  In  the  requirements  area  were  that  requirements  are  not 
stated  In  a  form  suitable  for  software  development  (this  will  hardly  come  as  a  surprise), 
that  they  are  not  kept  updated  after  the  initial  design  phase,  that  even  had  they  been 
current,  the  documents  are  not  In  a  format  useful  for  maintenance  organizations,  and  that 
the  most  pressing  questions  that  arise  In  later  life  cycle  stages  are  not  addressed.  The 
maintenance  problems  mostly  related  to  the  fact  that  the  available  documentation  was  too 
detailed  to  provide  the  needed  overall  perspective  for  personnel  who  have  not  participated 
in  the  original  development  —  read:  lack  of  requirements  documentation. 

The  larger  manifestations  of  the  problems  voiced  In  the  survey  are  familiar  to  most  software 
managers  responsible  for  large  systems: 

♦Inability  to  Improve  the  performance  of  a  frequently  used  module  because  no  one  Is 
certain  why  obviously   Inefficient  control   or  data  structures,  multiple 
Initializations  of  a  single  variable,  and  multiple  loops  for  what  appears  to  be  a 
single  Iteration  sequence  are  necessary 
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*  the  necessity  to  guess  the  amount  of  effort  required  to  achieve  a  new  Interface  or 
to  implement  a  new  function  because  the  time  available  for  furnishing  an  estimate 
does  not  permit  digging  Into  the  detail  level  (and  that  is  the  on  I  y<  one  for  which 
current  Information  exists) 

*the  large  effort  required  to  develop  requirements  for  a  new  system  that  is  Intended 
to  be  functionally  equivalent  to  an  existing  one. 

The  root  cause  of  these  problems  Is  that  most  requirements  documentation  (or  what  survives 
of  It  after  the  Initial  design  phase)  is  being  prepared  by  programmers  for  use  by 
programmers.  These  documents  do  not  address  the  needs  of  managers  who  have  to  make 
decisions  about  program  redesign,  program  enhancements,  or  possible  replacement  of  an  entire 
software  system.  Yet,  these  decisions  have  very  large  economic  consequences,  and  the  lack 
of  Information  Is  very  costly.  On  the  other  hand,  furnishing  this  Information,  if  It  Is 
made  an  Integral  part  of  the  software  management  process,  is  quite  inexpensive. 

The  thesis  of  this  paper  is  therefore  to  suggest  an  economical  means  for  Implementing 
management  oriented  requirements  documentation  that 

*  supports  the  needs  of  the  post-design  phases 

*  is  easily  maintained 

*  serves  as  top  level  of  an  overall  requirements  structure. 

The  purpose  to  be  addressed  by  the  proposed  documentation  is  amplified  In  the  following 
section.  A  specific  structure  and  formats  for  the  new  documents  are  then  described,  and 
suitable  interfaces  with  existing  formats  for  requirements  are  discussed.  It  Is  believed 
that  the  resulting  documentation  will  be  especially  suited  for  medium  and  large  scale 
software  or  total   Information  processing  systems. 


2.    USES  OF  REQUIREMENTS  DOCUMENTS 

The  conventional  view  is  that  requirements  documents  are  being  generated  during  the 
Definition  Stage  of  the  Development  Phase  to  guide  later  efforts  in  the  preparation  of 
specifications  and  other  Design  Stage  documents.  This  constitutes  Indeed  a  major  purpose  of 
requirements  documents,  and  it  Is  the  one  addressed  by  significant  studies  In  the  field 
IIYEH80,  ALF077I1  and  by  software  tools  for  the  automation  of  requirements  documentation 
CIEEE77I].  But  It  Is  by  no  means  the  only  one.  Other  Important  uses  for  requirements 
documents  are: 

Test  Case  Generation  -  Initial  and  updates 

Software  Maintenance  -  identification  of  possible  deletions 

Major  Modifications  -  definition  of  the  required  changes 

Replacement  -  point  of  departure  for  new  requirements. 

All  of  these  take  place  late  In  the  Development  Phase  or  after  It  Is  complete.  It  is 
frequently  held  that  at  that  point  in  time  there  Is  no  longer  a  need  for  requirements 
documentation  since  'more  definitive'  (really  meaning  more  detailed)  reports  and 
descriptions  are  available.  Although  the  Importance  of  requirements  documents  In  later  life 
cycle  phases  Is  acknowledged  In  several  of  the  previously  cited  references  and  Is  the 
specific  subject  of  a  more  recent  study  [DAVISO],  there  has  been  little  published  on  the 
format  and  content  of  requirements  documents  that  addresses  their  use  In  the  post-design 
period.  Because  of  this  neglect,  requirements  documentation  Is  not  kept  current,  and  this 
can  have  very  adverse  cost,  schedule,  and  performance  Impact  on  later  activities  as  Is  shown 
by  some  examples  below. 

The  generation  of  at  least  a  portion  of  the  test  cases  from  the  requirements  document  (as 
distinct  from  the  specification  or  program  description)  facilitates  the  discovery  of 
mistakes  In  the  translation  of  requirements  Into  the  subsequent  documents.  Under  most 
current  practices  the  use  of  the  requirements  document  as  a  basis  for  test  case  generation 
uncovers  Inadequate  updating  of  the  requirements  more  frequently  than  It  uncovers  design  or 
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programming  errors.  Test  cases  are  therefore  generated  without  reference  to  the 
requirements,  and  an  important  source  of  software  errors  is  being  neglected  In  the  test 
program. 

Practically  all  software  contains  segments  or  features  that  support  temporary  requirements 
such  as  handling  an  old  file  format  during  the  conversion  period,  servicing  obsolete 
peripherals  that  are  still  used  as  back-up  equipment,  or  generating  data  for  a  function  that 
will  shortly  be  transferred  to  another  agency.  If  the  requirements  document  identifies  the 
temporary  nature  of  these  features,  the  code  sections  that  implement  them  can  be 
appropriately  commented,  and  their  deletion  can  be  systematically  accomplished  as  part  of 
future  software  maintenance.  Conversely,  If  such  a  designation  of  temporary  requirements  Is 
not  provided,  and  if  later  updates  do  not  prune  obsolete  requirements,  the  code  will  soon 
become  a  jungle  of  unusued,  sometimes  even  Inaccessible,  segments  which  at  the  very  least 
cause  inefficient  use  of  memory,  frequently  entail  performance  penalties,  and  lead  to 
maintenance  problems. 

Major  modifications  of  programs  may  become  necessary  because  of  new  legislation,  a  change  In 
mission  or  weaponry  in  the  military  environment,  or  the  introduction  of  new  computer 
hardware.  In  all  cases  the  availability  of  current  and  succinct  requirements  documents  will 
facilitate  (a)  establishing  the  scope  of  the  software  modification,  (b)  assigning  budgetary 
and  management  responsibilities  for  the  execution,  and  (c)  the  integration  of  the  software 
changes  with  correlated  activities,  such  as  hardware  Installation  or  a  new  pattern  of  report 
distribution.  Use  of  existing  requirements  documents  in  the  management  of  a  major 
modification  also  provides  good  assurance  that  the  documents  will  be  kept  updated  as  the 
modification  is  implemented.  Where  requirements  have  not  been  kept  current,  the 
modification  must  be  planned  on  the  basis  of  more  detailed  documents  which  are  usually  not 
suitable  for  use  at  the  appropriate  level  of  management.  As  a  result,  there  Is  much  greater 
chance  that  some  necessary  steps  might  be  overlooked,  that  there  might  be  inefficient 
assignment  of  responsibilities,  and  that  functions  no  longer  required  will  be  carried  over 
Into  the  new  version.  Moreover,  there  are  seldom  adequate  resources  to  generate 
comprehensive  requirements  documentation  for  the  modified  version,  and  as  a  result  a  further 
deterioration  In  visibility  of  requirements,  and  hence  for  rational  management  of  the  entire 
software  effort,  will  have  occurred. 

The  importance  of  current  requirements  documents  for  the  existing  system  In  the  procurement 
of  a  replacement  is  often  overlooked.  Planning  for  the  replacement  of  a  major  software 
system  (frequently  coupled  with  new  hardware  procurement)  can  occupy  a  significant  fraction 
of  the  time  of  senior  management.  In  Federal  agencies  this  task  is  further  compi  Icated  by 
the  desire  to  avoid  commitment  to  a  single  vendor  at  a  very  early  stage.  As  a  result, 
requirements  planning  is  either  carried  out  in-house  (rarely  possible  because  of  the  heavy 
drain  on  senior  staff  time),  contracted  out  to  a  company  not  eligible  to  participate  In  the 
procurement  (inevitably  causing  inefficiency  In  Information  transfer),  or  conducted  in 
parallel  by  multiple  vendors  (with  obvious  cost  penalties).  Where  the  current  requirements 
of  the  existing  system  are  not  well  documented,  they  are  at  this  point  reconstructed  in  a 
process  that  by  Its  nature  Is  extremely  Inefficient. 

Under  current  budgetary  constraints  it  seems  Incredible  that  more  attention  is  not  being 
called  to  the  many  cost  penalties  that  arise  when  requirements  documentation  Is  Inadequate 
or  not  kept  current.  Yet,  this  condition  is  the  rule  rather  than  the  exception.  The 
explanation  is  most  likely  in  the  diffuse  manner  in  which  the  lack  of  requirements 
documentation  makes  Itself  felt.  Once  the  specification  Is  written,  there  Is  Indeed  no 
activity  that  comes  to  a  screeching  halt  because  requirements  are  inadequate  or  obsolete. 
On  the  other  hand,  the  effort  required  to  generate  good  requirements  documentation  and  to 
keep  it  current  is  easily  identified  and  therefore  frequenly  avoided.  It  Is  believed  that 
this  effort  Is  sometimes  overestimated,  and  that  current  concepts  of  requirements 
documentation  address  an  uncalled  for  level  of  detail.  These  statements  are  amplified  In 
the  followig  section. 


3.     STRUCTURE  OF  REQUIREMENTS  DOCUMENTS 

Because  the  emphasis  In  this  paper  is  on  the  use  of  requirements  documents  In  the 
post-design  period,  when  the  need  to  access  them  will  be  sporadic,  the  following  addresses 
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primarily  the  structure  for  hard  copy  versions.  If  the  requirements  documents  can  be  kept 
resident  on  a  computer,  the  automated  search  facilities  that  will  then  be  available  may  make 
It  possible  to  consider  other  formats.  Again  because  of  the  contemplated  sporadic  use  by 
personnel  who  will  not  necessarily  be  familiar  with  the  specific  software,  or  who  may  not  be 
software  professionals  at  all,  the  use  of  specialized  requirements  languages  and  of  formal 
syntax  will  not  be  acceptable.  Moreover,  at  the  top  requirements  level  (which  Is  the 
crucial  one  In  the  present  context)  these  procedures  contribute  comparatively  little  to 
clarification  of  a  natural  language  text.  On  the  other  hand,  the  use  of  decision  tables  or 
of  graphics  may  be  helpful  supplements  to  text  statements. 

Because  of  the  concern  with  ease  of  use.  It  Is  desirable  to  keep  Individual  requirements 
documents  reasonably  small,  say  between  25  and  50  pages  of  text.  Obviously,  this  Is  not 
sufficient  to  record  the  requirements  for  even  a  medium  size  software  system  at  the  level  of 
detail  that  will  support  the  activities  outlined  in  the  previous  section.  The  way  out  of 
this  difficulty  Is  to  provide  a  hierarchy  of  requirements  documents.  Thus,  the  top  level 
document  will  contain  general  requirements  levied  against  the  entire  system  (see  Section  4) 
and  those  detail  requirements  which  must  be  Implemented  at  the  system  level,  such  as 
sequencing  and  abort  criteria  for  the  next  lower  level  functions.  For  all  other 
requirements,  reference  is  made  to  the  requirements  document  for  the  appropriate  function. 
Two  levels  of  requirements  documents  will  be  adequate  for  many  applications;  for 
exceptionally  large  or  complex  systems,  three  levels  might  be  necessary.  The  hierarchical 
structure  also  improves  the  maintainability  of  the  documents  as  Is  explained  below. 

Downward  referencing  should  be  by  volume  designation  only,  consistent  with  the  general 
principle  of  Information  hiding  In  hierarchical  structures.  This  also  assures  that  detail 
revisions  to  lower  level  documents  can  be  made  without  Impact  on  the  higher  level  document. 
On  the  other  hand,  to  assure  traceablllty  of  requirements,  upward  referencing  should  be  very 
specific  (to  the  lowest  pertinent  indentation  in  the  parent  document).  Through  use  of  a 
one-way  cross-reference  (parent  paragraph  to  descendant  paragraph),  bound  with  the  lower 
level  document.  It  Is  then  possible  to  Identify  all  provisions  In  a  given  document  that 
might  be  affected  by  a  change  in  the  parent.  An  example  of  a  top  level  requirements 
structure  and  the  use  of  forward  and  backward  referencing  is  shown  in  figure  1. 

It  must  be  realized  that  the  assignment  of  functions  from  a  single  higher  level  document  to 
a  number  of  lower  level  documents  Is  a  des Ign  activity.  There  is  frequently  considerable 
latitude  in  the  partitioning,  and  hence  opportunity  for  choices  that  will  be  questioned  at  a 
later  time.  A  statement  of  the  rationale  for  the  assignment  of  functions  to  the  Individual 
lower  level  elements  should  therefore  be  Included  In  each  parent  document. 

The  structure  of  each  lower  level  document  Is  also  a  design  process,  frequently  tied  to  an 
acknowledged  or  unacknowledged  perception  of  the  implementation.  It  might  be  pedantic  and 
unproductive  to  require  a  justification  for  each  subdivision  of  a  document  that  Is  not 
directly  dictated  by  requirements  at  a  higher  level.  However,  where  a  document  is 
structured  after  some  deliberation,  a  brief  notation  of  the  rationale  will  be  very  helpful 
for  future  uses,  particularly  for  those  associated  with  major  modifications  or  replacement. 

The  hierarchically  structured  requirements  documents  can  be  supplemented  by  a  volume  that 
contains  Information  common  to  the  entire  project  such  as  definitions,  abbreviations,  units 
of  measurement,  common  file  and  report  formats,  and  the  Identification  of  the  common 
hardware  environment.  Provision  of  such  a  volume  not  only  avoids  repetition  of  these  items 
In  each  requirements  document  (and  In  other  software  documentation  as  well)  but  also 
simplifies  the  updating  when  any  of  the  common  items  are  changed.  A  technical  report 
currently  In  the  draft  stage  by  the  American  National  Standards  Committee  on  Information 
Systems  (ANSC  X3)  can  be  used  as  a  guide  in  the  preparation  of  the  common  project 
information  [ANSCSO]. 


4.    THE  TOP  LEVEL  REQUIREMENTS  DOCUMENT 

Considerable  effort  has  gone  Into  defining  what  needs  to  be  stated  In  a  requirements 
document  in  order  to  enable  the  design  of  a  program  to  render  an  accurate  and  efficient 
Implementation  of  these  requirements.     The  previously  cited  references,  particularly 
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VOLUKE  1 

SYSTEM  REQUIREMENTS 
1 .  SYSTEM 

1.1  REQUIREMENT  A  [DOCUM.  T] 
1  .2  REQUIREMENT  B  [0/3.1] 


RE  FE  RENlf:?'"4'11^ofeAT  I  ON 

1.  DEFINITIONS 

2.  INPUT  FORMATS 

2.1  INPUT  A  [DOCUM.  P] 

2.2  INPUT  B  [DOCUM.  Q] 


3.  REPORT  FORMATS 

3.1  REPORT  A  [DOCUM.  R] 

3.2  REPORT  B  [DOCUM.  S] 


2.     SUBSYTEM  I   (SEE  VOL.  2-1 ) 

2.1  REQUIREMENT  A  [1/1  .1] 

2.2  REQUIREMENT  B 


I    3.     SUBSYSTEM  II   (SEE  VOL  2-2]  | 


VOLUFC  2-1 

FUNCTION  1  REQUIREMENTS 
1 .     SUBSYSTEM  I 

1 .1  REFINE  REQ'MT  A  [1/2. f 

1.2  REFINE  REQ'MT  B  [1/2.2. 


2.    COMPONENT  a 

2.1  REQUIREMENT  A  [2-1/1 .1] 

2.2  REQUIREMENT  B  [0/3.2] 


3.    COMPONENT  b 

3.1  REQUIREMENT  A  [2-1/1.2] 

3.2  REQUIREMENT  B  [0/3.2] 


LEGEND 

[Y/Z]  BACKWARD  REFERENCE  TO  VOLUME  Y,  PAR.  Z 
OR  TO  AN  EXTERNAL  DOCUMENT 


SOURCE 

THIS 

DOCUM. 

VOLUME 

0/3.2 

2.2 

3.2 

1/2.1 

1.1 

1/2.1 

1  .2 

2-1/1.1 

2.1 

2-1/1 .2 

3.1 

FIGURE  1  -  EXAMPLE  OF  TOP  LEVEL  REQUIREMENTS  STRUCTURE 
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[YEHSOU,  provide  good  summaries  of  this  work  and  the  present  contribution  Is  not  intended  as 
an  Improvement  in  that  area.  However,  even  the  best  documents  that  are  concerned  solely 
with  design  do  not  provide  much  of  the  information  needed  for  effective  use  of  requirements 
documents  in  later  life  cycle  phases.  This  information  Includes  the  authorization  for  the 
project,  the  specific  legislative  or  administrative  orders  that  It  implements,  and  the 
constraints  that  were  considered  in  the  framing  of  the  requirements.  Many  peculiarities  of 
large  programs  arise  from  these  Items  but  their  origin  tends  to  be  forgotten.  Thus,  when 
the  causes  or  constraints  are  later  removed,  the  program  elements  or  structure  that 
implemented  them  are  allowed  to  persist,  freqently  through  many  revisions  and  even 
rep  I acements. 

This  Is  one  of  the  causes,  possibly  the  principal  one,  of  the  loss  of  structure  in  large 
programs  to  which  Belady  and  Lehman  called  attention  llBELA76l!.  From  their  observations,  the 
authors  coined  the  'Law  of  Increasing  Entropy':  "The  entropy  of  a  system  (its 
unstructuredness )  increases  with  time,  unless  specific  work  is  executed  to  maintain  or 
reduce  it."  If  the  unstructuredness  is  allowed  to  Increase,  the  performance,  the 
reliability,  and  the  maintainability  of  the  program  can  all  be  expected  to  decrease.  On  the 
other  hand,  the  'specific  work'  to  clean  up  a  program  that  has  been  in  service  for  some  time 
Is  likely  to  be  a  major  effort.  This  effort  can  be  reduced  by  current,  complete,  and 
accessible  documentation.  In  the  requirements  area,  much  of  the  information  needed  to 
maintain  programs  well-structured  (such  as  the  items  cited  in  the  preceding  paragraph),  is 
readily  available  during  the  early  stages  of  a  project  and  can  be  recorded  at  negligible 
cost. 

For  the  structure  described  In  the  previous  section,  the  top  level  requirements  document  Is 
the  logical  place  for  this  Information  that  usually  affects  the  entire  computer  system  (or 
at  least  the  software).  For  military  activities,  a  format  that  Is  suitable  for  capturing 
most  of  the  pertinent  data  is  the  Navy's  Operational  Requirements  Document  for  Tactical 
Digital  Systems  |lNAVY74l].  An  example  of  a  modification  of  this  for  use  in  a  more  general 
environment  Is  shown  in  Table  1. 

A  number  of  the  items  In  this  table  are  also  contained  In  the  Feasibility  Study  Document 
format  of  FIPS  PUB  64  CNBS793.  However,  they  are  embedded  there  In  a  document  that  Is 
Intended  to  support  the  Initiation  phase  and  can  not  be  expected  to  be  kept  updated 
throughout  the  software  life  cycle. 

Two  characteristics  of  the  above  outline  deserve  specific  attention:  most  of  the  entries  do 
not  lend  themselves  to  processing  by  current  requirements  analysis  tools,  and  many  of  the 
areas  covered  are  not  usually  of  concern  to  programmers  and  analysts.  Indeed,  the  top  level 
requirements  document  is  deliberately  management  oriented.  It  is  intended  to  be  prepared 
under  the  immediate  direction  of  the  management  that  provides  the  funding  for  the  entire 
system  development  or  procurement,  and  it  is  intended  to  be  used  by  management  responsible 
for  the  development  of  the  individual  major  system  segments,  by  the  management  responsible 
for  maintenance,  and  then  again  by  the  management  level  that  funds  major  modifications  and 
eventual  replacement  (this  will  usually  be  the  same  organization  that  prepared  it  but  most 
likely  not  the  same  personnel). 

5.    LOWER  LEVEL  REQUIREMENTS  DOCUMENTS 

The  second  level  requirements  document  usually  addresses  software  at  the  level  at  which  the 
major  development  effort  Is  segmented.  The  divisions  can  be  by  type  of  use  (operational, 
operations  support,  maintenance,  simulation  and  training),  or  by  applications  served.  The 
top  level  document  Is  fully  visible  at  this  stage,  and  all  applicable  provisions  of  the 
general  requirements  identified  there  should  be  referenced  rather  than  copied.  This 
eliminates  the  need  for  multiple  documentation  changes  (possibly  poorly  synchronized  or  not 
carried  out  completely),  when  a  top  level  requirement  Is  changed.  Allocations  of 
requirements  are  normally  identified  in  the  top  level  document  (e.  g.,  allocation  of  overall 
performance  requirements  to  the  major  segments),  but  the  Implementation  of  this  allocation 
and  the  further  allocation  to  lower  segments  need  to  be  covered  In  the  second  level 
documents.  Upward  referencing  must  be  complete  and  detailed  (to  the  lowest  pertinent 
indentation  In  the  parent  document). 

As  mentioned  earlier,  any  refinement  of  a  requirement,  and  particularly  the  allocation  of 
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TABLE  1  -  OUTLINE  OF  TOP  LEVEL  DOCUMENT 


1.  INTRODUCTION  I 

1.1  Purpose  of  proposed  system  and  respons i b I  I ty  for  implementation  ; 

1.2  Authorization  for  establishing  requirements  { 

1.3  Leg i si ative  requirements  implemented 

1.4  Administrative  requirements  implemented 

1.5  Internal  requirements  of  Issuer  of  this  document  implemented 

1.6  Scope  of  this  document 

1.7  Operational  concepts  (number  and  type  of  users,  etc.) 

1.8  Operating  modes  to  be  provided  for 

a.  normal  operation 

b.  operation  during  reduced  equipment  availability 

c.  cal Ibratlon  or  set-up 

d.  training  or  simulation 

e.  post-operational  audits 

1.9  Support  Programs  provided  or  required  for 

a.  program  test 

b.  equipment  test 

c.  personnel  training 

d.  performance  monitoring,  etc. 

2.  APPLICABLE  DOCUMENTS 

2.1  Legislative,  administrative,  or  internal  authorizations 

2.2  Standards,  recommended  practices  or  guidelines  for  technical  aspects 

2.3  Documents  governing  procurement  and  contracting 

3.  OPERATIONAL  REQUIREMENTS 

3.1  General  operational  requirements  (expansion  of  1.7) 

3.2.  N  Operational  requirements  for  each  of  the  modes  under  1.8 

3.3.  N  Performance  characteristics  for  each  mode 

3.4.  N  Accuracy  and  format  requirements  for  each  mode 

3.5  Constraints  (software  &  hardware  cost,  equipment  size,  portability) 

3.6  Interfaces  (may  be  separately  stated  for  each  mode) 

3.7  Segmentation  (time  phasing  for  procurement  or  initial  operation) 

3.8  Other  Implementation  requirements  (including  security  and  privacy) 

3.9  Requirements  for  modification  and  expansion 

4.  SOFTWARE  REQUIREMENTS 

4.1         General  software  requirements  (language,  file  structures,  etc.) 
4.2.N      Specific  software  requirements  for  each  mode  under  1.8,  Including 

a.  reference  to  next  lower  level  document 

b.  performance  and  other  requirements  allocated  at  top  level 

4.3  Software  quality  requirements 

4.4  Overall  test  requirements  (levels,  independence  of  test  organization 

4.5  Overall  documentation  requirements 

4.6  Rel iabi I ity/aval I abi I Ity/maintainabi I  ity  reporting  requirements 


requirements  to  lower  level  functions,  really  constitutes  a  design  activity.  As  much  as 
possible  of  the  rationale  for  these  design  decisions  should  be  documented,  and  the  second 
level  requirements  document  is  a  suitable  repository  of  such  decisions. 

For  military  applications  a  suitable  format  for  the  second  level  requirements  document  is 
the  Function  Operational  Specification  in  [NAVY74I].  An  example  of  an  adaptation  of  this 
for  use  In  a  more  general  environment  is  shown  in  Table  2. 

As  might  be  expected,  second  level  documents  contain  more  of  the  information  associated  with 
the  software  development  process.  Many  of  the  requirements  listed  In  Table  2  (particularly 
under  headings  3.  and  4.)  are  equivalent  to  those  of  Sections  3  and  4  of  the  FIPS  PUB  38 
Functional  Requirements  Document  CNBS76I1.  While  these  documents  thus  represent  a  transition 
from  the  primarily  management  oriented  top  level  document  to  the  technical  software 
development  requirements,  their  information  content  can  be  more  readily  supplied  by  project 
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TABLE  2  ~  OUTLINE  OF  SECOND  LEVEL  DOCUMENT 


1 .  i  NTRODUCT I  ON 

1.1  Purpose  of  segment  and  responsibility  for  Implementation 

1.2  Functions  served  by  this  segment 

1.3  Scope  of  this  document 

1.4  Operational  concepts  for  this  segment  (number  and  type  of  users,  etc.) 

1.5  Operating  modes  for  this  segment 

1.6  Programs  (or  major  modules)  contained  In  this  segment 

1.7  Support  programs  required  for  this  segment 

2.  APPLICABLE  DOCUMENTS 

2.1  Parent  document 

2.2  Technical  documents  specifically  applicable  to  this  segment* 

2.3  Procurement  and  contracting  documents  specifically  applicable* 

3.  OPERATIONAL  REQUIREMENTS 

3.1  General  (Including  allocation  of  functions  to  programs) 

3.2  Basic  operations  (operator  and  user  Interactions  with  the  system) 
3,3.N     Specific  operations  (for  each  program) 

a.  normal  operation 

b.  operation  during  reduced  equipment  availability 

c.  calibration  and  set-up 

d.  training  or  simulation 

e.  post-operational  audits 

f.  Interaction  with  support  programs 

Under  each  of  the  above  headings,  describe  Input  preparation, 
processing,  use  of  output,  performance  and  accuracy  requirements, 
specific  rel labi Ity/aval labi I Ity  requirements,  and  Identification  of 
actions  that  must  be  avoided. 


4,  E(?UIPMENT  REQUIREMENTS 

4.1  Minimum  equipment  requirements 

4.2  Optional  equipment  for  Improved  performance  or  further  capabilities 

4.3  Equipment  requirements  for  expansion 

5,  INTERFACES 

5.1  External  Interfaces* 

5.2  Interfaces  with  other  system  segments 

5.3  User  Interfaces  (human  engineering  requirements) 

6,  OTHER  REQUIREMENTS 

6.1  Software  quality  requirements  (Including  availability)* 

6.2  Test  and  validation  requirements 

6.3  Documentation  requirements 

6.4  Rel lab  1 1 1 ty/aval I ab 1 1 Ity/mal ntal nab  1 1 Ity  reporting  requirements* 

6.5  Security  and  privacy  requirements 

6.6  Requirements  for  modification  and  expansion* 

7,  CROSS  REFERENCE  (Top  level  provisions  Incorporated  In  this  document) 


*  This  Information  needs  to  be  provided  only  If  It  differs  from  that  in  the  top  level 
requirements  document 


management  than  by  software  professionals,  and  It  Is  therefore  suggested  that  they  also  be 
prepared  under  the  direction  of  a  management  function. 

For  very  large  software  systems,  a  third  level  of  requirements  documents  may  be  generated, 
primarily  In  order  to  keep  the  page  count  within  a  range  that  permits  easy  access  to  the 
desired  Information.  Where  the  second  level  requirements  documents  have  been  broken  down  by 
applications  area,  the  third  level  may  be  divided  by  type  of  use  (operational,  support, 
etc),  or  vice  versa. 
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The  second  (or  third)  level  documents  normally  serve  as  inputs  to  specific  requirements 
documents  for  each  program  to  be  developed  or  procured.  Their  purpose  is  to  describe  in 
detail  the  operational  and  functional  requirements  to  a  level  of  detail  suitable  for 
procurement,  including  criteria  for  the  evaluation  of  each  requirement.  The  Navy's  Program 
Performance  Specification  [NAVYSO]  and  the  System/Subsystem  Specification  of  FIPS  PUB  38  may 
be  utilized  for  this  purpose. 

Beyond  their  essential  role  for  software  development,  the  second  level  requirements 
documents  should  provide  background  information  that  Is  vital  for  the  Intelligent  and 
efficient  use  of  the  software  throughout  Its  operational  life.  if  the  information  is 
recorded  as  It  Is  being  developed  (I.  e.,  directives  for  planning  and  development,  memoranda 
of  understanding,  etc.),  the  cost  for  the  documentation  Is  low.  If  it  has  to  be  retrieved 
at  a  later  time,  the  cost  Inevitably  rises.  After  some  time  the  nature  of  the  pertinent 
Information  becomes  lost  (no  one  remembers  that  the  software  structure  was  governed  by  a 
certain  memorandum)  and  the  Information  becomes  completely  unavailable.  The  effort  for 
restoring  structure  to  a  program  under  these  conditions  usually  exceeds  the  available 
resources,  and  a  completely  fresh  start  becomes  necessary. 

6.  CONCLUSIONS 

Requirements  documents  can  provide  valuable  information  for  software  lifecycle  phases  that 
follow  design  and  Implementation,  but  current  approaches  do  not  meet  these  needs  and  It  Is 
suspected  this  causes  much  economic  loss.  To  overcome  these  difficulties,  a  hierarchical 
structure  for  software  requirements  documentation  has  been  proposed  that  (a)  limits  the  size 
of  each  volume  so  that  It  can  be  easily  handled  and  read,  and  (b)  addresses  specific 
Information  needs  at  each  management  level.  The  hierarchical  documentation  Is  supplemented 
by  a  single  volume  that  contains  general  project  Information,  such  as  definitions, 
abbreviations,  and  report  formats.  This  structure  permits  economical  generation  of  the 
documents,  provides  traceablllty  of  requirements,  and  is  easy  to  maintain  because  usually  a 
change  can  be  Implemented  by  revision  of  a  single  document. 
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Issues  In  Defining  Standards  for  Documentation 
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Applied  Mathematics  Division 
Argonne  National  Laboratory 
9700  South  Cass  Avenue 
Argonne,  IL  60439 

INTRODUCTION 

Plato  remarked  that  we  are  all  metaphorically  seated  in  a  cave,  chained  to  look  only 
at  the  end  wall,  and  seeing  no  more  than  the  shadows  cast  by  real  objects  in  the  sunlight 
from  the  entrance. 

The  three  other  papers  in  this  session  portray  different  shadows  of  the  the  same 
thing  clearly  and  precisely.  But  the  object  has  more  than  three  dimensions,  and  I  would 
like  to  discuss  other  projections  I  have  seen  over  the  years.  A  good  standard  takes 
account  of  all  dimensions,  and  considers  principal  axes  instead  of  a  single  caliper 
measurement  taken  in  an  arbitrary  direction.  And  because  of  this,  instead  of  examining 
each  portrait  to  remark  on  mole  here  and  a  wart  there  in  the  subject,  I  am  going  to  do  a 
few  lightning  sketches  from  other  perspectives. 

The  first  step  in  understanding  what  standards  for  software  documentation  should  be 
like  is  to  understand  where  software,  software  documentation,  and  the  use  of  software  fit 
in  the  spectrum  of  human  activities  at  work.  This  question  has  been  studied  by  Rasmussen 
[1980],  who  has  classified  work  activities  as  skill-based,  rule-based,  and  knowledge- 
based.  Since  1776  the  distribution  of  human  work  among  these  categories  has  changed 
greatly . 

Two  hundred  years  ago  most  work  was  skill-based:  The  cabinet  maker  with  his  plane, 
the  shepherd  with  his  sheep  made  their  decisions  without  conscious  application  of  rules. 

The  Industrial  Revolution  mechanised  many  of  these  tasks,  enabling  only  the  most 
expert  practitioners  of  skills  to  compete  with  machines.  But  it  brought,  instead, 
administrative  work  to  manage  the  factories.  This  consisted  of  application  of  well- 
defined  rules  to  easily  recognized  situations.  By  1900  the  need  for  people  who  could  read 
rules  and  write  decisions  had  become  vital,  and  industrial  societies  were  developing 
public  education  systems  to  provide  universal  literacy. 

Since  1950,  computing  technology  has  been  gradually  making  the  average  rule-based 
workers  less  employable,  just  as  manufacturing  technology  did  their  skill-based  great- 
grandfathers between  1850  and  1900.  Nevertheless,  many  activities  remain  rule-based,  even 
when  this  approach  hinders  efficiency  ~  as  it  does  in  the  rule-based  documentation  for 
word  processors,  or  when  the  rules  create  resentment  —  as  they  do  among  medical  staff 
used  to  giving  rules  rather  than  having  rules  imposed  on  them  by  software  "assistants." 

Ironically,  although  software  may  be  used  by  people  trained  in  rule-based  work,  the 
task  of  writing  software  is  knowledge-based.  By  this  I  mean  that  it  consists  of  deter- 
mining facts,  choosing  hypotheses  from  a  "knowledge  base,"  pattern-matching  them  against 
the  facts,  and  acting  in  ways  determined  by  the  results.  The  same  is  true  of  writing 
documentation.       It     is     patently     ridiculous     to  write  standards  in  a  rule-based  style  to 


Ihis  work  was  supported  by  the  Applied  >fetheraatical  Sciences  Research  Program  (KC-04-02)  of  the 
Office  of  Energy  Research  of  the  U.S.  Department  of  Biergy. 
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govern  this  activity.  Unfortunately,  we  do  not  know  how  to  write  standards  for  knowled;>e- 
based  activity.  If  we  did,  it  would  be  as  easy  to  teach  style  and  semantics  as  it  is  to 
teach  syntax.     So  much  for  the  broadest  brush  in  the  paintbox. 

What  is  a  program?  It  is  two  things:  an  art  and  a  contract.  As  an  art  it  is  "sculp- 
ture in  thought  constrained  by  reality,"  where  correct  syntax  is  necessary,  but  style  and 
other  more  subtle  things  distinguish  good  from  bad.  Good  software  is  art  in  contract 
draftsmanship,  just  as  surely  as  Frank  Lloyd  Wright's  houses  are  in  brick  and  mortar.  The 
architectural  model  of  software  leads  to  the  following  thought.  Building  codes  set 
standards  for  housing  construction.  Are  there  similar  functions  in  a  set  of  standards  for 
documentation?  I  am  inclined  to  think  not.  Obviously,  rules  like  those  for  Ph.D.  theses 
about  the  use  of  100%  rag  bond  are  ridiculous.  Functional  rules  like  "a  roof  shall  be 
designed  to  withstand  150  pounds  per  square  foot  of  static  load,  and  an  additional  100 
pounds  per  square  foot  of  wind  load"  seem  attractive  until  we  realise  that,  although  it  is 
easy  to  verify  conformity  with  this  standard,  functional  requirements  for  documentation 
are  not  verifiable  in  a  way  that  would  clearly  stand  up  in  court.  I  have  written 
introductions  to  the  use  of  full-screen  text  editors  for  our  office  staff  and  was 
pleasantly  surprised  by  the  success  of  a  knowledge-based  document  where  the  knowledge  base 
was  set  out  with  some  care  at  the  beginning  by  examples.  But  I  have  no  idea  whether  this 
would  work  with  office  staffs  in  general. 

Leaving  the  architectural  model,  let  us  look  at  software  as  a  contract  between  users 
and  computer.  Before  the  contract  can  be  drawn,  the  draftsman  and  the  users  must  have  a 
meeting  of  the  minds  about  what  is  to  be  done.  This  is  the  requirements  document,  a  "meta 
contract"  or  "meta  program."  Standards  for  requirements  documents  are  thus  "meta  meta 
programs"  —  hardly  the  subject  for  rule-based  discourse. 

After  the  contract  has  been  drawn,  it  is  like  any  other  legal  document  — 
incomprehensible  to  the  user  (but  in  our  case,  oddly  enough,  precisely  comprehensible  to 
the  computer,  apart  from  bugs).  Therefore  it  needs  an  "interpretation"  full  of  "for 
instances."     This  is  the  set  of  user  manuals,  which  must  meet  three  needs: 

*  It  must  be  comprehensible  to  the  user  community.  In  particular,  it  must  present 
facts  about  using  the  software,  not  facts  from  which  these  may  be  deduced. 

*  It  must  cover  all  commonly  used  cases  and  show  the  path  to  higher  authority  which 
can  mediate  unusual  disputes  between  user  and  computer. 

*  Although  it  need  not  be  precise,  it  must  not  be  obviously  misleading. 

So  much  for  the  legal  drafting  and  artistic  models  of  software  development  and  use. 

COMMENTS 

I  will  now  add  my  own  experience  to  some  of  the  points  raised  by  the  other  papers  in 
this  session.  I  think  that  such  comments  are  worthwhile  not  only  because  the  ideas  are 
interesting  but  because  the  differences  of  emphasis  help  round  out  a  picture  of  the 
process . 

All  documentation  standards  are  context  dependent.  I  can  maintain  the  "C"  programs 
that  comprise  UNIX  with  no  other  documentation  than  the  source  code,  because  Brian 
Kernighan  will  not  let  in  the  door  anybody  who  has  not  read  The  Elements  of  Programming 
Styles  [Kernighan  and  Plauger,  1978]  (a  policy  that  is  a  meta  standard).  If,  on  the  other 
hand,  I  am  maintaining  the  load  modules  of  ADVENTURE  which  run  on  ray  Z80,  I  need  a 
document  in  English  to  work  with  the  program:  The  FORTRAN  source  is  virtually 
incomprehensible;  it  seems  to  have  been  transliterated  by  hand  or  machine  from  some  more 
suitable  AI  language,  preserving  only  the  instructions  to  the  computer  and  omitting  any 
explanation  of  the  original  writer's  intent.  There  are  issues  here  about  correctly 
matching  language  to  problems,  and  letting  the  compiler  do  the  dog  work,  that  suggest 
questions  about  transforming  information  from  one  representation  to  another.  These  issues 
are  important;  they  are  also  an  example  of  the  general  process  that  takes  a  product  from  a 
requirements  document  to  a  program,  removing  information  about  the  application  context  and 
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adding  information  about  the  target  computer  system.  By  and  large,  documentation  should 
preserve  and  extend  the  application  dependent  information  stripped  out  of  the  requirements 
by  a  programmer,  and  should  complement  and  explain  the  machine-dependent  information 
inserted.  This  information  which  goes  into  the  document  depends  on  how  much  applications 
information  is  left  in  the  program,  how  much  more  target  machine  information  is  needed  to 
make  the  program  do  something  desired  by  a  user,  and  how  much  the  user  community  may 
already  be  assumed  to  know. 

Discussions  of  documentation  as  a  QA  tool  make  another  important  point.  If  you  can't 
write  a  user  manual  because  you  can't  explain  how  to  use  the  program,  then  the  program  had 
better  be  rewritten  by  somebody  who  has  at  least  read  Kernlghan  and  Plauger  [1978]  .  The 
writer  of  user  documentation  needs  the  following  things: 

*  No  previous  experience  with  the  software  being  documented. 

*  The  ability  to  explain  clearly  in  writing. 

*  Means  to  obtain  experience  with  the  system  to  be  documented  by  running  it. 

*  A  clear  idea  of  what  the  users  want  the  program  to  do. 

*  A  document  written  by  the  programmer,  believed  to  be  a  user  manual,  from  which 
parts  of  the  content  of  the  user  manual  proper  can  be  deduced. 

*  Access  to  the  programmer  to  ask  questions  and,  ideally,  enough  programming 
experience  to  be  able  to  read  and  understand  the  source  code. 

*  Authority  to  require  a  review  by  project  management  in  cases  where  it  seems  that 
parts  of  the  program  should  be  rewritten. 

I  have  seen  the  importance  of  these  requirements  underscored  in  my  work  as  Chairman 
of  the  Board  of  Directors  of  a  small  software  company  (an  activity  I  pursue  in  my  spare 
time).  We  have  found  a  good  user  manual  to  be  our  most  effective  marketing  tool.  This 
should  imply  that  the  Vice  President  for  Marketing  is  an  important  ally  to  the 
documentation  team.  Similarly,  the  software  team  should  be  allies  also,  because  a  good 
user  manual  will  save  them  field  maintenance.  But  such  allies  require  an  understanding 
management,  and  such  management  is  sometimes  difficult  to  find. 

Requirements  documentation  is  important  because  it  is  the  "draft  agreement"  between 
the  users  and  the  computer.  If  the  final  product  does  not  meet  requirements,  and  the 
need,  was  not  documented  there  is  bound  to  be  a  bitter  dispute  about  who  pays  for 
necessary  changes.  Nevertheless,  requirements  documents  often  are  not  written  at  all,  and 
those  that  are  often  are  not  very  good.     Two  of  the  reasons  are  discussed  below. 

*  The  cost  of  a  requirements  document  is  "money  up  front."  From  the  user's  point  of 
view  this  appears  unnecessary  risk  capital,  compounded  by  interest  rates  as  the  clock 
ticks  until  the  project  is  finished.  Low  bidders,  who  promise  to  work  without 
requirements,  may  seem  far  more  attractive.  If  you  want  a  customer  to  pay  for  a 
requirements  document,  you  must  be  credible  about  the  benefits  and  your  ability  to  deliver 
them,  right  down  to  a  better-than-average  user  manual. 

Your  most  powerful  marketing  tools  are  horror  stories  about  what  happened  to  projects 
that  were  careless  about  requirements  documentation.  On  such  projects  as  nuclear  electric 
generating  plants,  for  example,  the  costs  of  slippage  late  in  the  project  can  be  as  high 
as  a  million  dollars  a  day.  Of  course,  deadlines  invariably  slip.  If  you  are  a  good 
salesman  and  your  customer  is  reasonable,  you  will  be  able  to  prepare  for  this  kind  of  bad 
news,  before  you  both  sign  a  contract.  (Unfortunately,  such  things  happen  only  in  the 
best  of  all  possible  worlds.) 

*  It  is  difficult  to  ensure  that  the  requirements  document  contains  the  information 
needed.  Two  questions  must  be  answered:  "What  is  it  for?"  and  "Who  will  use  it?"  As 
answers  to  these  questions  change,  so  too  must  the  requirements  document  change.  Thus  a 
full  requirements  document  has  two  parts:     one  a  prospect,     which     is  what  we  try  to  write 
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now,  and  the  other  a  retrospect,  which  should  be  —  and  almost  never  is  —  written  after 
all  else  is  done. 

Finally,  documentation  in  general  raises  an  AI  theoretic  issue.  Most  of  us  are 
familiar  with  the  model  of  a  finite-state  machine  which  consists  of  nodes  joined  by  paths, 
along  which  the  incoming  data  stream  causes  transitions  between  the  nodes.  A 
generalisation  of  this  seems  to  me  to  be  a  reasonable  description  of  knowledge  and,  in 
fact,  is  one  theoretical  foundation  for  data  bases  that  contain  knowledge,  i.e.,  knowledge 
bases.  It  is  a  set  of  networks,  where  all  the  items  at  about  the  same  level  of  generality 
form  a  network  that  you  can  wander  around  using  a  process  (i.e.,  program)  to  travel  from 
node  to  node.  The  well-known  ADVENTURE  game  is  Just  such  a  network,  although  the  process 
there  is  designed  to  give  you  a  puzzle  to  solve  rather  than  a  guidebook.  If  you  add  to 
this  network  a  feature  where  you  can  also  descend  vertically  from  each  node  into  a  network 
of  more  detailed  information  about  that  node,  and  make  this  feature  Indefinitely 
repeatable  at  will,  you  have  a  computer-based  process  that  seems  to  me  remarkably  like  the 
human  process  of  mental  information  retrieval.  As  you  descend  into  detail  about  some 
particular  node,  information  about  other  unrelated  topics  at  a  higher  level  becomes  less 
accessible  in  much  the  same  way  as  nonrelated  knowledge  retires  into  the  background 
mentally  while  we  think  intensely  about  one  thing. 

CONCLUSIONS 

The  notion  of  a  documentation  standard  has  been  developed  as  a  sort  of  box  or  pattern 
into  which  documents  fit.  The  nature  of  the  box  is  not  yet  properly  defined  to  anybody. 
But  it  does  seem  close  to  ideas  about  representation  of  knowledge  that  have  been  developed 
by  the  AI  community  since  the  early  1970's  [Woods  1970,  Barr  and  Feigenbaum  1980]. 

And  some  things  do  seem  clear.  Documentation  should  meet  the  needs  of  several  kinds 
of  users.  It  should  be  in  modules  that  can  be  "strung  together,"  so  that  the  same  infor- 
mation is  not  written  in  several  places.  The  master  copy  should  be  machine  readable  so 
that  a  computer  can  help  with  the  inevitable  updates.  There  may  be  several  modules 
dealing  with  the  same  subject  at  different  levels  of  detail.  In  such  cases  cases  it 
should  be  easy  to  travel  vertically  through  a  set  of  more  detailed  modules,  as  well  as 
horizontally  from  one  module  to  another  about  something  different  at  the  same  technical 
level.  All  of  these  travel  processes  should  be  easy  to  perform  in  documentation  on  paper, 
and  should  be  facilitated  on  a  computer  by  an  intelligent  process  that  remembers 
frequently  used  paths  for  any  given  user.  The  conqjuter- based  travel  process  should  have  a 
richer  set  of  commands  than  the  one  on  paper,  which  is  probably  restricted  to  UP,  DOWN, 
and  SIDEWAYS,  speaking  in  metaphorical  terms. 

A  final  theoretical  issue  that  seems  to  me  to  be  important  is  the  idea  of  "transfor- 
mation." A  program  is  obtained  by  a  "transformation"  of  a  "requirements  document."  The 
fact  that  the  transformation  is  performed  by  people  does  not  alter  the  central  question  of 
what  information  is  discarded,  what  information  is  added,  and  what  information  should  be 
moved  to  documentation.  In  fact,  under  this  model  the  documentation  is  just  as  much  a 
transformation  of  the  requirements  as  the  program  is.  The  process  of  writing  documenta- 
tion consists  of  transforming  the  program,  the  requirements,  and  the  description  of  the 
computing  environment  into  a  precis  that  covers  most  user  needs  and  is  not  too  heavy  to 
hold!  A  standard  for  writing  this  precis  has  its  theoretical  foundation  in  a  description 
of  what  kinds  of  knowledge  should  be  preserved  by  the  transformation  and  how  to  leave 
pointers  in  the  precis  to  let  the  user  find  the  material  that  was  not  preserved.  Covering 
all  needs  is  impossible;  that  is  what  the  manuals  for  the  computing  environment,  the 
customer's  detailed  procedures,  and  the  program  do  together.  In  the  case  of  dispute  with 
the  system  not  resolved  by  the  documentation,  these  together  with  the  computer  system 
itself  are  the  final  court  of  appeal. 
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AN  AQCNOWLED^ENT  AND  A  NOTE 


The  final  text  of  this  paper  was  prepared  by  Gail  Pieper,  using  the  notes  from  which 
I  spoke  as  a  draft.  This  gracious  lady  has  firmly  refused  a  co-authorship^  and  so  the 
following  acknowledgment  takes  its  place.  Thank  you,  Gail,  for  your  part  in  the  work  here 
recorded. 

Gail's  effort  in  transforming  my  recollections  into  publishable  form  brought  to  the 
surface  some  thoughts  I  had  been  nursing  about  the  relationship  between  software  and 
documentation.  Almost  twenty-five  years  ago,  when  I  wrote  my  first  computer  programs,  it 
was  a  Herculean  task  to  do  anything,  and  explaining  it  in  writing  afterwards  was  trivial 
by  comparison.  Today  I  look  at  a  large  program,  part  of  a  research  project  by  three 
colleagues  which  took  eighteen  months  of  part-time  work  for  them  to  write.  I  do  not  think 
anybody  will  be  able  to  document  the  system  in  detail  to  display  its  subtle  yet  clean  and 
beautiful  architecture  without  being  an  expert  in  several  very  difficult  fields  at  once. 
The  effort  involved  here  in  programming  and  documenting  will  be  roughly  equivalent, 
depending  on  where  you  put  the  tasks  of  analysis  and  specification. 

This  situation  may  easily  become  true  of  most  programs.  They  will  still  be  written 
by  software  artisans.  But  they  will  not  be  used  without  equal  contributions  from 
"wordsmiths , "  who  have  been  using  syntax  and  semantics  to  build  perceptions  ever  since  the 
first  minstrel,  long  before  Aristophanes.  The  wordsmith's  Cask  will  have  been  recognised 
for  what  it  really  is:  one  leg  of  a  tripod  support  for  a  software  edifice,  the  other  two 
being  analytical  insight  into  the  problem  at  hand,  and  the  art  of  program  contract 
draftsmanship. 
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Session  H:    Quality  Assurance  for  Documentation 

Recommendations  and  Conclusions 

Elisabeth  F.  Mullen 

Managing  Partner 

JEM  Associates 
Herndon,  Virginia 

Following  the  presentation  of  papers  which  are  included  in  these  proceedings  along  with 
the  discussant's  remarks,  there  was  a  lively  discussion  among  members  of  the  audience 
and  the  panel.    A  summary  of  the  issues  raised,  comments,  and  recommendations  follows. 

Issues  raised  by  members  of  the  audience  included: 

1.  The  relation  between  the  Users'  Manual  and  the  Requirements  Document:    Should  the 
first  draft  of  the  former  be  done  from  the  latter? 

2.  Is  the  Users'  Manual  needed  in  order  to  complete  testing? 

3.  Is  there  not  a  need  for  more  than  one  type  of  Users'  Manual? 

4.  What  is  known  about  the  cost  benefits  of  spending  money  on  documentation?    Is  the 
investment  returned  in  easier  maintenance  or  greater  reliability? 

Comments  on  these  issues  included  the  following: 

1.  Caroline  Levenson  commented  on  the  desirability  of  removing  some  of  the  duplication 
of  effort  implied  by  the  current  standard. 

2.  John  Gabriel  commented  that  the  artificial  intelligence  community  has  tried  to 
address  the  issue  of  different  requirements  for  different  groups  of  users  and 
mentioned  that  there  are  some  on-line  documentation  systems  which  use  these  ideas. 

3.  Herb  Hecht  commented  that  large  systems  tend  to  sink  under  the  weight  of  their  own 
changes.    Often  they  must  be  rewritten  because  they  can  no  longer  be  maintained. 
This  is  where  a  good  requirements  document  is  especially  important. 

4.  John  Gabriel  pointed  out  the  desirability  of  documenting  the  history  of  a  system  as 
well  as  its  use.    Examples  included  unusual  origins  for  system  routines  and  the 
need  to  replace  computer  systems  which  are  part  of  systems  with  life  times  much 
longer  than  that  of  the  computer  hardware. 

Recommendations  emerging  from  the  session  include  the  following: 

1.  FIPS  38  does  need  to  be  evaluated. 

2.  Both  the  content  and  the  context  of  the  Users'  Manual  need  to  be  reexamined  in  the 
light  of  current  technology. 

3.  Several  different  types  of  users'  manuals  may  be  needed  depending  on  the  background 
and  assignments  of  the  users.    Differentiating  between  the  requirements  of  new  and 
experienced  users  is  desirable.    The  widely  varying  needs  of  the  operations  staff, 
maintenance  programmers,  and  managers  who  must  justify  both  the  operating  budget 
and  the  eventual  replacement  of  the  system  should  also  be  considered  in  determining 
both  the  number  of  types  of  manuals  and  their  content. 
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4.  The  importance  of  considering  the  human  interface  was  mentioned  repeatedly,  with  a 
strong  emphasis  on  providing  enough  flexibility  in  the  standard  to  allow  for  some 
experimentation  with  new  approaches  in  this  area. 

5.  The  project  history  may  well  be  a  valid  subject  for  a  full  set  of  documentation. 

6.  There  do  not  seem  to  be  any  hard  facts  on  the  incremental  value  of  documentation, 
i.e.  is  the  cost  of  documentation  returned  in  increased  maintainability  or 
reliability?    A  study  of  this  might  be  rewarding  in  terms  of  improved  quality 
resulting  from  cost  justifying  the  additional  budget. 
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Concluding  Session: 

Summary  of  Findings  and  Recommendations 

Leo  Beltracchi 

U.S.  Nuclear  Regulatory  Commission 

The  concluding  session  of  the  workshop  was  moderated  by  Albrecht  Neumann.    Each  session 
moderator  of  the  previous  sessions  presented  a  summary  of  the  findings  and  recommendations 
of  their  session.    Comments  and  recommendations  were  also  made  by  other  members  of  the 
workshop.    This  provided  an  opportunity  for  all  participants  to  hear  and  comment  upon  the 
findings  of  the  workshop.    A  brief  summary  of  the  concluding  session  follows. 

Alfred  Sorkowitz,  moderator  of  Session  D,  "Do  Existing  Standards  Work?",  presented  the 
results  of  the  session.    These  were: 

1.  FIPS  PUB  38  is  inadequate  and  should  be  revised.    Examples  of  the  subjects 
which  need  consideration  are:    software  security,  non-machine  interactions . 

2.  To  improve  software  documentation,  it  was  recommended  that  technical  writers  be 
made  a  unique  part  of  the  design  and  development  team.    This  would  improve  the 
importance  of  software  documentation  and  the  quality  of  the  final  product. 

The  results  of  a  session  survey  on  the  use  of  documentation  standards  were  also 
presented.    The  results  indicated  that  organizations  used  in-house  standards  rather 
than  a  national  standard  for  documentation. 

Louis  O'Korn  of  Session  A,  "Applying  Documentation  Standards  -  Case  Studies"  presented 
the  results  of  the  session.    These  were: 

1.  Existing  software  documentation  standards  provide  good  "How  To"  guidance.  How- 
ever, they  are  inadequate  with  regards  to  guidance  on  interactions  by  humans  with 
computers,  they  are  redundant  in  requirements,  and  they  lack  general  guidance  to 
the  documenter. 

2.  New    documentation  standards  are  needed  for  all  phases  of  software.  Specific 
attention  should  be  given  to  the  operations  and  maintenance  phase  of  the  life- 
cycle  and  to  the  testing  of  software  in  the  development  phase. 

3.  More  research  is  needed  on  documentation  aspects  for  office  automation.  The 
issues  of  user  implemented  software,  how  to  verify  documentation  and  automated 
support  tools  for  the  non-computer  professional  must  be  resolved.    Means  should  be 
found  to  publicize  existing  documentation    guidelines,  and  standards. 

4.  It  was  noted  a  general  lack  of  awareness  of  documentation  standards  exist. 

5.  The  need  for  documentation  must  be  defined  in  the  initial  work  effort. 

Raymond  Houghton,  moderator  of  Session  C,  "Tools  for  Improved  Documentation", 
presented  the  following  comments: 

1.    Documentation  standards  in  hard  copy  have  a  tendency  to  become  obsolete  after  some 
time.    With  a  rapidly  moving  technology  they  need  to  be  updated  frequently,  and 
must  provide  for  introduction  of  new  documentation  techniques. 
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2.  Some  high  level  languages  also  provide  human  readable  information  which  can  augment 
other  forms  of  documentation.    This  should  be  used  in  the  overall  systems  develop- 
ment and  systems  design. 

3.  Documents  and  documentation  are  an  integral  and  active  part  of  an  overall  software 
life  cycle.  Software  tools  can  play  an  important  part  in  creating  better  and  more 
cost  effective  documentation.  Active  management  support  is  required  and  necessary 
to  achieve  these  goals. 

4.  On-line  documentation  can  serve  as  a  "users  manual".    Split  screen  techniques  can 
be  used  effectively.    An  integrated  system  of  HELP  messages,  designed  with  several 
levels  of  generality  also  can  provide  useful  user  documentation.  Interactive 
techniques,  combined  with  split  screen  displays  can  be  used  effectively  as  user 
documentation. 

5.  Fully  automated  systems  to  perform  user  documentation  for  computer  programs  are  not 
yet  feasible  at  this  time,  and  are  5  to  10  years  away. 

V.  Douglas  Mines  of  Session  G,  "Improving  Human  Interface",  presented  the  following 
resul ts  : 

1.  Computer  systems  must  be  made  more  friendly  to  users.    This  will  require  user 
documents  tailored  to  needs  of  each  user  audience. 

2.  New  innovative  approaches  should  be  investigated  to  serve  information  needs  of 
users,  such  as  the  use  of  color  terminals,  "comic  book  style"  users  manuals,  and 
on-line  documentation. 

3.  Terminal  messages  can  be  used  as  on-line  documentation  support  for  the  user. 

4.  People  must  be  trained  to  develop  better  documentation  for  computer  systems. 

5.  Use  software  and  systems  documentation  in  the  training  of  personnel. 

Lenore  Maruyama,  moderator  of  Session  F,  "Enhancing  Software  Sharing",  presented  the 
following  results: 

1.  Additional  elements,  such  as  a  header  label  to  record  bibliographic  information 
describing  a  machine-readable  data  file  are  needed. 

2.  FIPS  30  "Software  Summary  for  Describing  Computer  Programs  and  Automated  Data 
Systems"  should  be  revised  and  updated. 

3.  As  a  tool  for  management,  software  sharing  facilities  can  be  used  to  save  time  and 
money. 

Trudy  Grieb,  moderator  of  Session  E,  "Proposals  for  Documentation  Standards",  presented 
the  following  results: 

1.  A  systems  approach  is  needed  to  generate  documentation.    The  issue  of  the  cost  and 
effectiveness  of  documents  in  terms  of  users  needs  and  contract  requirements  must 
be  resolved. 

2.  Documentation  standards  must  be  specific  and  definitive  with  regards  to  context, 
terms  and  concepts,  but  must  be  flexible  to  allow  cost  effective  innovations. 

3.  Lessons  learned  from  poor  documentation  should  be  recorded  to  avoid  repeating  the 
error.    Also,  the  lessons  learned  from  good  documentation  should  be  recorded  to 
provide  feedback  and  guidance  to  standard  developers. 

4.  Because  of  the  large  consumer  market,  documentation  for  microcomputers  may  lead  the 
effort  for  standards. 

Virginia  Walker,  moderator  for  Session  H,  "Quality  Assurance  for  Documentation", 
reported  the  following  results: 
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1.  FTPS  38  needs  to  be  revised  and  updated. 

2.  Documents  must  strive  to  make  the  human  interface  with  computers  an  easy  one. 

3.  Management  must  recognize  the  role  of  documents  in  the  life  cycle  of  softv;are 
such  as  the  function  of  configuration  control  in  program  design  and  development. 

4.  Software  documents  must  not  only  define  what  is  recorded,  but  also  the  reason 
why  it  is  recorded. 

5.  Documents  for  software  must  be  logically  oriented,  well  structured,  and  not 
fragmented . 

At  the  conclusion  of  the  summaries  by  the  moderators,  Al  Neumann  asked  for  comments  from 
the  floor.    The  following  comments  represent  the  major  comments  from  the  floor: 

1.  Electronic  mail  and  teleconferencing  can  be  used  to  develop  standards  and  guide- 
lines for  software  documentation.    These  methods  allow  for  the  participation  of 
many  people  and  reduces  the  need  for  periodic  meetings. 

2.  We  should  strive  to  modularize  documentation.    Documentation  for  microprocessors 
is  modularized  and  this  accounts  for  its  popularity.    This  concept  eases  the 
organization  and  control  of  document  generation. 

3.  The  need  for  documentation  must  be  emphasized.    This  can  best  be  achieved  by 
defining  the  functional  basis  for  the  document.    Software  which  does  not  have 
good  documentation  generally  can  not  be  trusted. 

Upon  termination  of  audience  comments,  Al  Neumann  thanked  all  participants  for  their 
contributions  and  then  closed  the  workshop. 
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